Download O2 Spatial User Manual

O2 Spatial
User Manual
Release 5.0 - April 1998
In for m ation in t h is docu m en t is su bject t o ch an ge with ou t
n ot ice an d sh ou ld n ot be con str u ed as a com m it m en t by
O2 Tech n ology.
Th e soft war e descr ibed in th is docu m en t is deliver ed u n der a
licen se or n on disclosu r e agr eem en t.
Th e soft war e can on ly be u sed or copied in accor dan ce wit h t h e
ter m s of th e agr eem en t . It is again st t h e law t o copy t h is
soft war e t o m agn et ic t ape, disk , or an y ot h er m ediu m for an y
pu r pose ot h er t h an t h e pu r ch aser ’s own u se.
Copyr igh t 1992-1998 O 2 Tech n ology.
All r igh t s r eser ved. No par t of t h is pu blicat ion can be
r epr odu ced, st or ed in a r et r ieval syst em or t r an sm it t ed in an y
for m or by an y m ean s, elect r on ic, m ech an ical, ph ot ocopy
with ou t pr ior wr itt en per m ission of O2 Tech n ology.
O2 , O 2 En gin e API, O2 C, O2 DBAccess, O2 En gin e, O2 Gr aph ,
O2 Kit , O2 Look , O2 St or e, O2 Tools, an d O2 Web ar e r egist er ed
tr adem ar k s of O2 Tech n ology.
SQL an d AIX ar e r egist er ed t r adem ar k s of In t er n at ion al
Bu sin ess Mach in es Cor por at ion .
Su n , Su n OS, an d SOLARIS ar e r egist er ed t r adem ar k s of Su n
Micr osystem s, In c.
X Win dow System is a r egist er ed tr adem ar k of t h e
Massach u set t s In st itu t e of Tech n ology.
Un ix is a r egist er ed t r adem ar k of Un ix Syst em Labor at or ies, In c.
HPUX is a r egist er ed t r adem ar k of H ewlet t -Pack ar d Com pan y.
BOSX is a r egist er ed t r adem ar k of Bu ll S.A.
IRIX is a r egist er ed t r adem ar k of Siem en s Nixdor f, A.G.
NeXTSt ep is a r egister ed t r adem ar k of t h e NeXT Com pu t er , In c.
Pu r ify, Qu an t ify ar e r egist er ed tr adem ar k s of Rat ion al Soft war e
In c.
Sear ch ’97 is a r egist er ed t r adem ar k of Ver it y In c.
Win dows is a r egist er ed t r adem ar k of Micr osoft Cor por ation .
All oth er com pan y or pr odu ct n am es qu ot ed ar e t r adem ar k s or
r egist er ed t r adem ar k s of t h eir r espect ive t r adem ar k h older s.
Who should read this manual
This manual presents the O2 spatial indexing module. This module allows you to
develop efficient applications managing geographical information. The manual
describes how to create, delete, update and query a spatial index associated
with a collection of persistent objects. The O 2 spatial index module provides
both high-level C++ and low-level O 2Engine API programming tools for spatial
indexing. This manual contains a comprehensive list of O2Spatial methods and
commands.
Other documents available are outlined, click below.
See O2 Documentation set.
1
TABLE OF CONTENTS
Th is m an u al is divided in t o t h e followin g ch apt er s:
1 - I n t r od u c t i on
2 - S et t i n g u p O 2 S p a t i a l
3 - U si n g O2Sp at i al
4 - O 2 S p a t i a l C + + A PI r ef er en c e
5 - S p a t i a l I n d ex i n g w i t h O 2 E n gi n e A PI
O2Spatial User Manual
5
TABLE OF CONTENTS
1
Introduction
9
1.1 System overview ......................................................................10
1.2 O2 : Efficient support for Geographical Info Systems..........12
1.3 The O2Spatial module..............................................................13
1.4 Object storage and retrieval....................................................14
2
Setting Up O2Spatial
17
O2HOME Files ............................................................................18
Schema initialization....................................................................18
3
Using O2Spatial
21
3.1 Spatial index creation and deletion ........................................23
The creation and deletion commands...........................................23
Spatial index options ....................................................................23
3.2 C++ Interface to a spatial index ..............................................25
3.3 Spatial Index Constructor........................................................27
3.4 Spatial Index update ................................................................27
Insertion and removal methods ....................................................27
Update method .............................................................................29
3.5 Spatial Index tuning .................................................................29
The O2 spatial index options .......................................................29
3.6 Querying....................................................................................30
Types of queries ...........................................................................30
O2 Spatial keys ............................................................................31
Spatial query examples ................................................................31
Spatial predicate parameters ........................................................34
How to query spatially .................................................................34
Using object methods...................................................................34
Using OQL predicates..................................................................35
Examples ......................................................................................36
6
O2Spatial User Manual
TABLE OF CONTENTS
4
O2Spatial C++ API Reference
39
4.1 Class definitions ...................................................................... 40
4.2 Member functions descriptions ............................................. 44
close_to........................................................................................ 45
contain ......................................................................................... 46
d_GeoCollection (constructor) .................................................... 47
d_GeoCollection (constructor) .................................................... 48
insert_element.............................................................................. 49
insert_elements ............................................................................ 50
inside............................................................................................ 51
intersect........................................................................................ 52
operator=...................................................................................... 53
remove_element .......................................................................... 54
remove_elements ......................................................................... 55
update_element............................................................................ 56
clone ............................................................................................ 57
d_SpatialKey2D (constructor)..................................................... 58
d_SpatialKey2D (constructor)..................................................... 59
d_SpatialKey3D (constructor)..................................................... 60
d_SpatialKey3D (constructor)..................................................... 61
dimension .................................................................................... 62
enlarge ......................................................................................... 63
getInternalKey ............................................................................. 64
getSize ......................................................................................... 65
isAPoint ....................................................................................... 66
o2_get_name................................................................................ 67
operator=...................................................................................... 68
operator+= ................................................................................... 69
5
Spatial Indexing with O2Engine API
71
5.1 Introduction.............................................................................. 72
5.2 O2 Engine API : Spatial Index................................................. 72
INDEX
95
O2Spatial User Manual
7
TABLE OF CONTENTS
8
O2Spatial User Manual
1
1
I ntr oduction
The O2Spatial module provides spatial indexing and search capabilities for any
collection of persistent objects in your O2 database.
This chapter presents an overview of the O2 system, an introduction to spatial
indexing technology, and a brief overview of O2Spatial.
To effectively use this manual, you should have some knowledge of O2, its C++
ODMG binding interface and of OQL.
O2Spatial User Manual
9
1
Introduction
1.1 System overview
Th e syst em ar ch it ect u r e of O2 is illu st r at ed in Figu r e 1.1.
External
Interfaces
Development Tools
Standard
Dev. Tools
O2 Dev. Tools
OQL
C
O2 C
C++
Database Engine
Java
O2Spatial
O2Engine
O2Store
O2ODBC
O2Corba
O2DB
Access
O2Web
Fi gu r e 1 .1 : O2 Sy st em Ar ch i t ect u r e
Th e O 2 system can be viewed as con sist ing of t h r ee com pon en t s. Th e
Database Engine pr ovides all t h e feat u r es of a D at abase syst em an d an
object -or ien t ed syst em . Th is en gin e is accessed wit h Development Tools ,
su ch as var iou s pr ogr am m in g lan gu ages, O 2 developm en t t ools an d an y
st an dar d developm en t tool. Nu m er ou s External Interfaces ar e pr ovided.
All en com passin g, O 2 is a ver sat ile, por t able, dist r ibu t ed, h igh per for m an ce dyn am ic object -or ien ted dat abase system .
Database En gin e:
10
• O2 St or e
Th e dat abase m an agem en t syst em pr ovides low level
facilit ies, t h r ou gh O2 Stor e API, t o access an d m an age a
dat abase: disk volu m es, files, r ecor ds, in dices an d
t r an sact ion s.
• O2 En gin e
Th e object dat abase en gin e pr ovides dir ect con t r ol of
sch em as, classes, object s an d t r an sact ion s, t h r ou gh
O2 En gin e API. It pr ovides fu ll t ext in dexin g an d sear ch
capabilit ies wit h O 2 Sear ch an d spat ial in dexin g an d
r et r ieval capabilit ies wit h O 2 Spat ial. It in clu des a
Not ificat ion m an ager for in for m in g oth er clien t s
con n ect ed t o t h e sam e O 2 ser ver t h at an even t h as
occu r r ed, a Ver sion m an ager for h an dlin g m u lt iple
object ver sion s an d a Replicat ion API for syn ch r on izin g
m u lt iple copies of an O2 system .
O2Spatial User Manual
System overview
Pr ogr am m in g Lan gu ages:
O 2 object s m ay be cr eat ed an d m an aged u sin g t h e followin g
pr ogr am m in g lan gu ages, u tilizin g all t h e featu r es available wit h O2
(per sist en ce, collection m an agem en t , t r an sact ion m an agem en t , OQL
qu er ies, et c.)
• C
O2 fu n ct ion s can be in vok ed by C pr ogr am s.
• C++
OD MG com plian t C++ bin din g.
• J ava
OD MG com plian t J ava bin din g.
• O2 C
A power fu l an d elegan t object-or ien t ed fou r t h
gen er at ion lan gu age specialized for easy developm en t
of object dat abase applicat ion s.
• OQL
OD MG st an dar d, easy-t o-u se SQL-lik e object qu er y
lan gu age wit h special feat u r es for dealin g wit h com plex
O2 object s an d m eth ods.
O 2 Developm en t Tools:
• O2 Gr aph
Cr eat e, m odify an d edit an y t ype of object gr aph .
• O2 Look
Design an d develop gr aph ical u ser in ter faces, pr ovides
in t er active m an ipu lation of com plex an d m u ltim edia
object s.
• O2 Kit
Libr ar y of pr edefin ed classes an d m et h ods for fast er
developm en t of u ser applicat ion s.
• O2 Tools
Com plet e gr aph ical pr ogr am m in g en vir on m en t t o
design an d develop O 2 dat abase applicat ion s.
St an dar d Developm en t Tools:
All stan dar d pr ogr am m in g lan gu ages can be u sed wit h st an dar d
en vir on m en t s (e.g. Visu al C++, Su n Spar cwor k s).
Exter n al In t er faces:
• O2 Cor ba
Cr eat e an O2 / Or bix ser ver t o access an O2 dat abase
wit h CORBA.
• O2 DBAccess Con n ect O2 applicat ion s to r elation al dat abases on
r em ot e h ost s an d in vok e SQL st at em en ts.
• O2 OD BC
Con n ect r em ot e ODBC clien t applicat ion s t o O2
dat abases.
• O2 Web
Cr eat e an O2 Wor ld Wide Web ser ver t o access an O 2
dat abase th r ou gh t h e in t er n et n etwor k .
O2Spatial User Manual
11
1
Introduction
1.2 O2 : Efficient support for Geographical Info
Systems
The growth of computational power and memory capacities with the proliferation
of personal computers has brought about the development of complex
information systems.
Different forms and types of information can be represented as spatial data,
such as medical images, satellite images, geographical information, etc.
Geographical entities require a high level model to be represented in a
computational form. A geographical entity is by nature likely to be very complex.
For instance a town map is made up of many different items such as streets,
houses, parks, which can be themselves divided up into smaller parts. Each
item has coordinates, scales and properties on a map.
The object model is very appropriate to capture this complexity, because of the
natural and efficient way in which it describes each part as an object as well as
the combination of items as composite objects. Thus O2 is the perfect system to
store and organize geographical information.
In order to be useful, such a repository should enable you to retrieve as fast as
possible the information which you are interested in. Because of the
geographical nature of the queries, they are linked to the topological properties
of the objects. Some examples of queries are : which cities are near Paris?
Which objects does New York City include? What rivers cross this town? etc.
All these geographical operators work using graphical coordinates, which may
be of a planar, a three-dimensional nature, or higher dimension as is the case of
a hyper model. To efficiently answer such types of queries you need data
structures and quick-access paths, which can deal with the coordinates of such
items.
This is precisely the reason why you use a spatial index. The spatial index plays
the same role regarding “geo-referenced” objects (i.e. objects referenced to by
their coordinates) as a standard O2 index regarding the simple properties of
some objects (objects referenced to by the value of a simple attribute).
Similar to standard indexes (see chapter 5 in the System Administration Guide ),
a spatial index maps a key to a set of objects. The only difference lies in the
nature of the key used. For a standard index, a key is an atomic data (e.g.
integer, string...), whereas for a spatial index a key is a multi-dimensional data
(e.g. a pair of reals : x, y; or a triple of reals : x, y, z; or more). Such
multidimensional keys are called spatial keys.
12
O2Spatial User Manual
The O2Spatial module
1.3 The O2Spatial module
This document presents the O2 spatial indexing module. This module enables
you to develop efficient applications managing geographical information
(utilizing spatial indexing). The module uses the O2 ODMG C++ binding and the
OQL query language.
The spatial indexing module enables a programmer to create, delete, update
and query a spatial index associated with a collection of persistent geographical
objects.
This module provides the C++ programmer with an access to the spatial
indexing capabilities of the O2 system.
This document describes how to use spatial indexing, including creating and
deleting using the O2Shell, updating using C++, and querying using OQL and
C++.
The O2 spatial index module can also be used through a lower level
programming interface. Low-level programming tools are provided by the O 2
Spatial Index Engine API as well and described in Chapter 5, Spatial indexing
with O2Engine API.
O2Spatial User Manual
13
1
Introduction
1.4 Object storage and retrieval
The proliferation of personal computers and distributed servers, together with
the distribution of different forms and types of information across the World Wide
Web, has increased the demand for powerful information storage and retrieval
tools.
Spatial indexing enable users to search a large number of geo-referenced
objects using specific selection criteria. Early spatial indexing systems allowed
only 2-D objects. Today, spatial indexing systems are capable of efficiently
processing multidimensional objects and supporting user queries that address
specific object structures.
O2Spatial
O2Spatial enables application programmers to add spatial indexing and search
capabilities to any collection of persistent objects stored in an O 2 database.
An O2 application using O2Spatial can perform three functions:
• Index collections of persistent geo-referenced objects to make them efficiently
searchable
• Search and retrieve objects that satisfy users’ queries
• Maintain and optimize spatial indexes
O2Spatial applications can use the following search techniques:
• Searching for objects that intersect with a particular spatial point.
• Searching for objects that intersect with a certain window.
• Searching for objects that are inside a certain window.
• Searching for objects that are within a certain distance from a particular spatial point.
An application program interface (API) enables you to integrate spatial index
capabilities within your O2 applications.
Users’ perspective
From the user’s perspective, the primary interface to a spatial index is the query
language, which is used to search a collection of geo-referenced objects. To
offer the best flexibility and ease of use, ODMG OQL has been enhanced with
specific operators for spatial searches (spatial predicates like “intersect” and
“contain”). The result of a query is a set of objects or rectangular regions that
14
O2Spatial User Manual
Object storage and retrieval
satisfy the search criteria. The user can choose an object from the resulting list
and view it with an appropriate tool.
A C++ interface is provided which enables the user to manage the index as a
collection of (key, object) pairs. This indexing interface is used whenever you
want to add, update or delete an object from the spatial index.
R-Quad Tree
O2Spatial is a spatial indexing system capable of efficient storing and retrieval of
geo-referenced objects. This system is based on a Rectangle-Quadrant (RQuad) tree. The spatial index is maintained by the O2Spatial engine while the
objects are maintained in an O2 collection.
R-Quad tree based indexing and retrieval employs R-tree representation to
store and organize information, and Quad-tree representation to accelerate
spatial-based searching.
The main features of a spatial index based on a R-Quad tree architecture
include the following:
• powerful query language that supports point, window and proximity searches.
• fast maintenance when objects are added and deleted.
• efficient retrieval even for very large collections and very large query results.
Spatial representation
When using the O2Spatial engine, the spatial index stores a geo-referenced
object as a minimum rectangle (called bounding box) that encompasses the
object for identifying the spatial location of the object. To index an object, you
simply provide the object and its bounding box.
O2Spatial C++ API
Two C++ classes make up the O2Spatial API: d_GeoCollection and
d_SpatialKey.
O2Spatial indexes and searches instances of d_SpatialKey, which represent
indexed object keys.
An application can use methods in the d_GeoCollection class to search and
retrieve objects stored in a spatially indexed collections. These methods
produce lists of pointers to objects that satisfy the search criterion.
O2Spatial User Manual
15
1
16
Introduction
O2Spatial User Manual
2
Setting Up O2Spatial
2
Various O2 Spatial related files are needed to use the Spatial index. This
chapter presents how to set up your O 2 system in order to use O2 Spatial.
This chapter presents how to set up your O2 system to use O2 Spatial.
The chapter is composed of the following sections :
• O2HOME Files
• Schema initialization
O2Spatial User Manual
17
2
Setting Up O2Spatial
O2HOME Files
When you purchase O2, O 2 Spatial is available upon request. After installing O2,
you can find the following O2 Spatial-related files in your O2 home directory.
These files are needed to build an O2 Spatial application:
Include File/
o2spatial_CC.hxx
o2_spatialindex.h
- file you must include to use
the O2 Spatial C++ interface
- file which must be included
to use the spatial index
interface of the O2 Engine API.
o2_spatial.oql
- file you need to initialize
O2 schemas where spatial
queries will be performed
through OQL.
Libraries/
libo2si.so
libo2si_engine.so
- O2 Spatial interface
- standard O2 Spatial indexing
engine
You must add both libraries at link time when building a C++ application. This is
achieved automatically by O2Makegen. You just have to indicate in the
configuration file :
+UseSpatialIndex
Refer to the ODMG C++ Binding Guide and the O2 Makegen User Manual which
describe how to write and build a C++ application with O2.
When using the standard O2 Spatial indexing engine with the spatial index
interface of the O2 Engine API, you also need the following include files :
18
o2_SiArgList.hxx
SiEllipse.hxx
SiBoundingBox.hxx
SiPolygon.hxx
Si3DPoint.hxx
SiPolyline.hxx
O2Spatial User Manual
Schema initialization
Schema initialization
If you want to use spatial operators embedded in OQL queries, you must
initialize the O2 schema in which you are developing your application. To do so
run o2dsa_shell with your system and server name. Then use the set
schema command and include the OQL source file as follows :
$ o2dsa_shell -system your_system -server your_server
Type your command and end with ^D.
set schema your_schema;
#”O2HOME/include/o2_spatial.oql”
^D
O2Spatial User Manual
19
2
20
Setting Up O2Spatial
O2Spatial User Manual
3
3
U si n g O 2S p at i al
This chapter presents an example of a simple O 2Spatial application. The
example introduces the main components of the O2Spatial architecture and
shows how the O 2Spatial API can be used to build O2 applications that make
use of spatial indexing (SI) and retrieval capabilities. This example shows how
to manage a collection of geographical objects, create a spatial index for this
collection and carry out geographical queries. The geographical objects are
ellipses whose definition is given by the class appearing on the next page.
The complete description of the API is in chapter 4.
O2Spatial User Manual
21
3
Using O2Spatial
The geographical object class GeoEllipse is defined as follows :
class GeoEllipse
{
public:
// Constructor
GeoEllipse (
int center_x, int center_y, int radius_x, int radius_y);
// Specific methods
void moveCenter (int newXCenter, int newYCenter);
void stretch (int newXRadius, int newYRadius);
// Spatial key of this ellipse
d_SpatialKey2D* getSpatialKey () const;
// Private attributes.
private:
int
xCenter;
int
yCenter;
int
xRadius;
int
yRadius;
};
Note that a GeoEllipse object is defined by its center and lengths of its two
extremum axes. Such representation is not possible for the O 2 Spatial index, as
this sort of index can deal only with rectangles. Thus the class also needs the
getSpatialKey method, which returns the coordinates of the minimum
rectangle encompassing an ellipse. In the spatial index only such data (of
SpatialKey2D type) will be inserted.
22
O2Spatial User Manual
Spatial index creation and deletion : The creation
3.1 Spatial index creation and deletion
The creation and deletion commands
An O2 spatial index is created and deleted through the O2 database
administration shell, like any other O2 index (see the O2 System Administration
Guide). The O2DBA shell commands are the following:
create spatial index <collection-name>
[options "options-file-name"];
delete spatial index <collection-name>;
The create spatial index command creates a default spatial index
structure associated with a named collection of persistent objects. The user
then populates this index with the appropriate keys. The spatial index uses
various option parameters, which are detailed below.
The delete spatial index command deletes the spatial index associated
to a named collection of persistent objects.
The current spatial indexing system only allows a single spatial index for a given
collection. Other types of indexes are of course allowed with no limitations.
The following example defines a collection of ellipses, each of which being
represented by an instance of the C++ Class GeoEllipse. A spatial index is
created for this collection. Note that both GeoEllipse and
d_Set<d_Ref<GeoEllipse>> have been previously imported (see C++
Binding Guide).
constant name TheEllipses : o2_set_GeoEllipse;
create spatial index TheEllipses;
Spatial index options
The O2 spatial index module uses a generic indexing algorithm based on
R-Quadtrees. Each O2 spatial index is initialized with default parameter values
which may be customized as needed. For example, the dimensions of the keys
and indexing space boundaries may be set for each spatial index.
There are two ways to set parameters for a spatial index :
O2Spatial User Manual
23
3
Using O2Spatial
• Either using a configuration file, which is specified when the index is created with
o2dba_shell (in the options argument of the create spatial index command). This configuration file specifies a value for each option you want to customize, by providing a list of option=value (each on a separate line), where
option is the option name and value is its value for the parameter;
• Or using a low-level interface described in Chapter 5, Spatial Indexing with
O2Engine API .
The following options can be specified for the O2 spatial index (the configuration
file is not case-sensitive):
Option
Type
Description
Default value
IndexType
string
Name of the spatial index algorithm.
Must be “RQuadTree” to use the
O2Spatial indexing algorithm.
RQuadTree
Dimension
integer
Number of dimensions in the indexed
space.
2
KeyCoordType
string
Type used for spatial key coordinates,
either "Integer16" or "Integer32".
Integer32
For each dimension d (i.e. for each axis of the indexed space), the following
options can be specified:
Option
Type
Description
Default value
Dd_Min
KeyCoordType value
Minimum coordinate value for the
given dimension d.
KeyCoordType
minimum value.
Dd_Max
KeyCoordType
value
Maximum coordinate value for the
given dimension d.
KeyCoordType
maximum value.
Other options are available for optimization of the spatial index (see section 3.3
Spatial Index tuning).
24
O2Spatial User Manual
C++ Interface to a spatial index : Spatial index
Example :
Dimension
= 2
KeyCoordType
= Integer32
D1_Min
= 0
D1_Max
= 10000
D2_Min
= -100
D2_Max
= 1000
3.2 C++ Interface to a spatial index
Contrary to a standard index O2 does not automatically manage the spatial
index, but it provides a programmative interface to populate the index.
Although in a future O2 version, spatial indexes might be automatically
maintained whenever possible, this process is still not possible sometimes, as a
clear definition of a valid spatial key for a particular geographical object lacks.
Most of the time the application only knows how to approximate a geographical
object by a rectangle. For instance, in our example, the getSpatialKey
method only is able to compute the rectangle encompassing an ellipse.
It is thus generally impossible to determine when a spatial key has been
changed, and on performance grounds we prefer not to systematically call a
method, but rather rely on spatial keys directly passed by the programmer to
access the spatial index.
The O2 system enables the C++ programmer to manipulate a spatial index as a
collection of (key, value) pairs, such as the standard d_Dictionary ODMG
class. Like this standard class the O2 system uses the ODMG d_Association
structure to associate a key and its value.
O2Spatial User Manual
25
3
Using O2Spatial
template <class K, class V>
class d_Association
{
public:
K key;
V value;
d_Association();
d_Association(const K& K, const V& V);
};
The spatial index module introduces the d_GeoCollection, which is the C++
interface for accessing the O2 spatial indexes.
Like the standard d_Collection class, the d_GeoCollection class expects
only one template parameter, which is the indexed object class. The indexing
key class is assumed to be a subclass of the new abstract d_SpatialKey
class.
For convenience, two concrete subclasses d_SpatialKey2D and
d_SpatialKey3D, which inherit from the abstract d_SpatialKey class are
also defined.
d_SpatialKey
d_SpatialKey2D
26
d_SpatialKey3D
O2Spatial User Manual
Spatial Index Constructor : Insertion and removal
3.3 Spatial Index Constructor
To access the spatial index created in section 3.1 in C++, you have to use the
constructor in combination with a name. By convention, this name is the same
as that of the indexed collection.
d_GeoCollection<d_Ref<GeoEllipse> > Sindex(“TheEllipses”);
You can now populate the index with spatial key/GeoEllipse couples. At that
point it is up to the application to populate or not the collection itself (the
o2_set_GeoEllipse of the example). This is actually not compulsory, since
no automatic maintenance is carried out. The index may be enough, as it
represents a collection of the same objects.
3.4 Spatial Index update
Insertion and removal methods
The following methods are used to insert and remove spatial key/object couples
to/from the spatial index :
void d_GeoCollection<T>::insert_element
(const d_Association <d_SpatialKey*, T>& pair);
void d_GeoCollection<T>::remove_element
(const d_Association <d_SpatialKey*, T>& pair);
Indexing or deleting an array of pairs is more efficient than indexing or deleting
them individually, therefore two additional methods which manipulate arrays of
pairs are provided:
O2Spatial User Manual
27
3
Using O2Spatial
.
void d_GeoCollection<T>::insert_elements
(const d_Array <d_Association <d_SpatialKey*, T>>& pairs);
void d_GeoCollection<T>::remove_elements
(const d_Array <d_Association <d_SpatialKey*, T>>& pairs);
The following example shows how a geo-referenced object can be added to the
index.
d_Set<d_Ref<GeoEllipse> > Ellipses(“TheEllipses”);
d_GeoCollection<d_Ref<GeoEllipse> > Sindex(“TheEllipses”);
d_Association <d_SpatialKey*, d_Ref <GeoEllipse> >
pair;
d_Transaction transaction;
transaction.begin ();
// Set parameters for a new ellipse object.
int
center_x, center_y;
int
radius_x, radius_y;
cout << "Center:" << endl;
center_x = enter_number ("x=", 0, 32767);
center_y = enter_number ("y=", 0, 32767);
cout << "Radius:" << endl;
radius_x = enter_number ("x=", 0, 32767);
radius_y = enter_number ("y=", 0, 32767);
pair.value = new (database) GeoEllipse (
center_x, center_y, radius_x, radius_y);
pair.key = pair.value->getSpatialKey ();
// Insert the new object into the bag and the geo-collection.
Sindex.insert_element (pair);
Ellipses.insert_element (pair.value);
transaction.validate ();
28
O2Spatial User Manual
Spatial Index tuning : Update method
Update method
If a spatialKey/Object association is modified you must update the O2 system by
calling the following method:
void d_GeoCollection<T>::update_element
(const d_Association <d_SpatialKey*, T>& old_pair,
const d_Association <d_SpatialKey*, T>& new_pair);
Note that you must call the update method for each modified object of the
collection, by giving the values before update as well as the new values.
The complete C++ definition of the d_GeoCollection class and other
classes, which are specific to the spatial index C++ interface, is given in
Chapter 4.
3.5 Spatial Index tuning
The O2 spatial index options
O2 spatial indexes are maintained as R-QuadTrees. Several options enable
these trees to be adapted and optimized to the user needs, for instance by
allowing an R-QuadTree to be more balanced than the usual fixed QuadTree.
Firstly the number of dimensions used to describe a point in the indexed space
is by default two. For a larger number, it must be declared in the option
Dimension (up to O2 page size/KeyCoordType size).
With the key coordinate type option KeyCoordType , you can reduce the size of
the spatial index, by using a smaller key size (Integer16). Such a coarse-grid
representation may be sufficient for certain applications. For a fine-grid use the
default Integer32 format.
Specific coordinate boundaries can be defined with the “Dd_Min” and “Dd_Max”
options.
O2Spatial User Manual
29
3
Using O2Spatial
The full list of the O2 spatial index tuning options are the following:
Option
Type
Description
Default value
IndexType
string
Name of the spatial index algorithm.
Must be “RQuadTree” to use the
O 2Spatial indexing algorithm.
RQuadTree
Dimension
integer
Number of coordinates of the indexed
space.
2
OnlyPoints
boolean
True if indexed objects are always points.
False
KeyCoordType
string
Type used for spatial key coordinates.
Must be "Integer16" or "Integer32".
Integer32
Dd_Min
KeyCoordType
value
Minimum coordinate value for the given
dimension d (used for internal coordinates scaling optimization).
KeyCoordType
minimum value
Dd_Max
KeyCoordType
value
Maximum coordinate value for the given
dimension d (used for internal coordinates scaling optimization).
KeyCoordType
maximum value
Dd_Min
RegionSize
integer
Minimum size of an indexed region (in
KeyCoordType-based coordinates) for
dimension d. Such a region will not be
segmented more
2
3.6 Querying
Types of queries
A spatial index allows a user to run queries on geo-referenced data, and defines
spatial predicates to do so. Four types of queries are supported :
• The pointing predicate (called contain), where all the objects that include a
given point are retrieved,
• The windowing predicate (called intersect), where all the objects that
touch a given area are retrieved (they can project beyond the area boundaries),
• The strict windowing predicate (called inside), where all the objects that
are strictly within a given area are retrieved (i.e. none may project beyond
the area boundaries),
30
O2Spatial User Manual
Querying : O2 Spatial keys
• The closeness predicate (called close_to), where all the objects that are at
a given distance from a given point or a given area are retrieved (they can
project beyond the given distance).
Graphical examples for each of these predicates are given in a following
section.
Each spatial predicate is applied to bounding boxes (see figure below).
O2 Spatial keys
The geographical position of each object is stored in the index. The key type
used by the O2 spatial indexing module is the minimum rectangle containing the
indexed geographical objects, called the bounding box.
The bounding box principle is illustrated in the figure below:
ymax
ymin
xmin
xmax
Here a geo-referenced object (the triangle) is drawn in black, and its bounding
box is drawn in thin gray. When a bounding box has a surface area equal to zero
(i.e. where xmin = xmax and ymin = ymax), it is considered to be a point and
xmax and ymax may be omitted.
Spatial query examples
The following examples present some simple geometric queries.
O2Spatial User Manual
31
3
Using O2Spatial
• To retrieve all objects, which contain the point (x,y), from the spatial index
MyGeoObjects collection, the appropriate query is:
contain (MyGeoObjects, SpatialKey2D (x, y))
y
x
For this figure, the contain query returns the triangle and ellipse.
• Retrieve all the objects, which intersect with a specific window. This predicate
can be used to zoom in or zoom out in accordance with the definition of the specific window, for example:
intersect (MyGeoObjects,
SpatialKey2D (xmin, ymin, xmax, ymax))
ymax
ymin
xmin
xmax
For this figure, the intersect query returns the triangle, ellipse and trapezoid.
• Retrieve all the objects which are inside a specific window:
32
O2Spatial User Manual
Querying : Spatial query examples
inside (MyGeoObjects,
SpatialKey2D (xmin, ymin, xmax, ymax))
ymax
ymin
xmin
xmax
For this figure, the inside query returns the ellipse and pentagon, but neither
the triangle nor the trapezoid, since they project beyond the window limits.
• Retrieve all the objects which are within a given distance of a point:
close_to (MyGeoObjects, SpatialKey2D (x, y), dist)
x
y
dist
For this figure, the close_to query returns the triangle, trapezoid and
pentagon.
O2Spatial User Manual
33
3
Using O2Spatial
Spatial predicate parameters
In the previous section, we presented how to use spatial predicates (in terms of
points, rectangles and distances). This section describes the way these spatial
predicates are used in the C++/OQL interface with spatial indexes.
The O2 spatial index uses keys which are rectangles. Therefore such spatial
keys can map directly onto objects which are rectangles or represented as
rectangles. By extension, a point is considered as a zero-surface rectangle,
hence a zero-surface spatial key can map an object which is a spatial point or
represented as a point.
The notion of distance in multidimensional space makes sense only when the
units of the considered axes are the same. In that case, the distance unit is in
the given axis unit (remember that a distance is always a scalar and not a
vector). If the axes do not use the same units, the closeness predicate will return
incorrect results, and hence should not be used. Note that the closeness
predicate does not verify whether the spatial units are equivalent or not.
How to query spatially
There are two ways of querying a spatial index :
• By calling a C++ method of the d_GeoCollection class
• By using OQL
Using object methods
For each spatial predicate, a d_GeoCollection method is defined. Each of
these methods returns a d_Bag, which contains the found objects.
The following methods are defined in the d_GeoCollection class :
34
O2Spatial User Manual
Querying : Using OQL predicates
d_Bag<T> contain
(const d_SpatialKey& point);
d_Bag<T> intersect (const d_SpatialKey& window);
d_Bag<T> inside
(const d_SpatialKey& window);
d_Bag<T> close_to
(const d_SpatialKey& window,
d_Distance distance);
This object method querying approach offers a complete C++ solution to query
a spatial index. Moreover, since these methods return a bag of objects, they can
be applied in more complex queries, where both spatial and semantic
predicates are used.
The following example uses the C++ querying approach:
{
d_Bag <d_Ref <GeoEllipse> >
bagResult;
int
x, y;
cout << "Query point:" << endl;
x = enter_number ("x=", 0, 32767);
y = enter_number ("y=", 0, 32767);
bagResult = Sindex.contain (d_SpatialKey2D (x, y));
}
Using OQL predicates
For each spatial query type, a function callable by OQL is defined, as shown in
the following :
geo_contain (coll : Object, point : SpatialKey): o2_bag;
geo_intersect (coll Object, window : d_SpatialKey): o2_bag;
geo_inside (coll : Object, window : d_SpatialKey): o2_bag;
geo_close_to
(coll : Object, window : d_SpatialKey,
distance : Distance): o2_bag;
O2Spatial User Manual
35
3
Using O2Spatial
These functions should be explicitly included (see Chapter 2) in each schema
where these operators are to be used. Here, the Distance type is a named
type for double.
The above functions are similar to the d_GeoCollection query methods.
They return a bag of indexed objects, like the d_GeoCollection query
methods.
Like the d_GeoCollection query methods, these functions can be applied in
more complex queries, where both spatial and semantic predicates are used.
The following example uses the OQL querying approach :
{
d_Query query (“geo_intersect (TheEllipses, $1)”)
d_Bag <d_Ref <GeoEllipse> >
bagResult;
int
x, y;
cout <<“Query point:” << endl;
x = enter_number (“x=”, 0, 32767);
y = enter_number (“y=”, 0, 32767);
d_SpatialKey key (x, y);
query << &key;
d_oql_execute (bagResult, query);
}
Examples
Get all the hotels at a distance less than 5 kilometres from Colorado Falls:
36
O2Spatial User Manual
Querying : Examples
d_Query query (“geo_close_to (TheHotelsOfUSA, $1, $2)”);
query << ColoradoFalls->get position();
query << 5; // Distance in kilometers
Search a window (e.g. to zoom in) of coordinates (xmin, ymin, xmax, ymax) :
d_SpatialKey keyWindow (xmin, ymin, xmax, ymax);
d_Query query (“geo_intersect (MyGeoObjects, $1)”);
query << &keyWindow;
Get all the Sequoia forests which belong to the Yellowstone National Park and
whose surface is greater than 1,000 square kilometers :
d_Query query (“select forest”
“from forest in (o2_bag_Forest) geo_intersect (SequoiaForests, $1)”
“where forest.surface >= $2”);
The two parameters are :
query << YellowstonePark->getSpatialKey();
// a bag of forests
query << 1000;
// a surface.
If the intersect predicate is very selective this query runs fast. Otherwise if the
surface is very selective this query cannot use the standard index on the
attribute surface.
O2Spatial User Manual
37
3
Using O2Spatial
If you want to use both indexes1 then you must rewrite the query as an
intersection of the two result sets :
(o2_bag_Forest(select forest from forest in SequoiaForests
where forest.surface >= $2))
intersect
((o2_bag_Forest) geo_intersect (SequoiaForests, $1))
1. Note : in a future version of OQL, the OQL optimizer will rewrite this automatically
38
O2Spatial User Manual
O2Spatial C++
API Reference
4
4
The O2Spatial C++ API enables users to use O 2Spatial indexing and searching
facilities for a collection of persistent objects.
When an error is detected, O 2Spatial throws a ODMG C++ exception containing
an error code and description (see the class d_Error in the ODMG C++
Reference Manual).
This chapter describes the public interface of the C++ classes that make up the
O2Spatial API. The following classes are included:
• d_SpatialKey
• d_SpatialKey2D
• d_SpatialKey3D
• d_GeoCollection
O2Spatial User Manual
39
4
O2Spatial C++ API Reference
4.1 Class definitions
The public interface of the class is defined as follows:
typedef double d_Distance;
class d_SpatialKey : public d_Object
{
public:
d_SpatialKey ();
d_SpatialKey (const d_SpatialKey& key);
virtual ~d_SpatialKey ();
virtual d_SpatialKey* clone () const = 0;
// Dimension of the indexed space.
virtual int dimension () const = 0;
// O2 key class name.
virtual const char* o2_get_name () const = 0;
// Internal spatial key.
virtual const void* getInternalKey () const = 0;
// Internal spatial key size.
virtual int getSize () const = 0;
// Checks whether the key is a point.
virtual int isAPoint () const = 0;
// Enlarges the key.
virtual void enlarge (d_Distance distance) = 0;
// Assignment operator.
virtual const d_SpatialKey& operator= (const d_SpatialKey&);
// Key union operator.
virtual const d_SpatialKey& operator+= (const d_SpatialKey&);
};
40
O2Spatial User Manual
Class definitions
class d_SpatialKey2D : public d_SpatialKey
{
public:
d_SpatialKey2D (long x, long y);
d_SpatialKey2D (long xmin, long ymin,
long xmax, long ymax);
d_SpatialKey2D (const d_SpatialKey2D& key);
virtual ~d_SpatialKey2D ();
virtual d_SpatialKey* clone () const;
// Return 2.
virtual int dimension () const;
virtual const char* o2_get_name () const;
virtual const void* getInternalKey () const;
virtual int getSize () const;
virtual int isAPoint () const;
virtual void enlarge (d_Distance distance);
virtual const d_SpatialKey& operator= (const d_SpatialKey&);
virtual const d_SpatialKey& operator+= (const d_SpatialKey&);
// Return
long xmin
long xmax
long ymin
long ymax
the key coordinates.
() const;
() const;
() const;
() const;
};
O2Spatial User Manual
41
4
O2Spatial C++ API Reference
class d_SpatialKey3D : public d_SpatialKey
{
public:
d_SpatialKey3D (long x, long y, long z);
d_SpatialKey3D (long xmin, long ymin, long zmin, long xmax, long ymax,
long zmax);
d_SpatialKey3D (const d_SpatialKey3D& key);
virtual ~d_SpatialKey3D ();
virtual d_SpatialKey* clone () const;
// Return 3.
virtual int dimension () const;
virtual const char* o2_get_name () const;
virtual const void* getInternalKey () const;
virtual int getSize () const;
virtual int isAPoint () const;
virtual void enlarge (d_Distance distance);
virtual const d_SpatialKey& operator= (const d_SpatialKey&);
virtual const d_SpatialKey& operator+= (const d_SpatialKey&);
// Return
long xmin
long xmax
long ymin
long ymax
long zmin
long zmax
the key coordinates.
() const;
() const;
() const;
() const;
() const;
() const;
};
42
O2Spatial User Manual
Class definitions
template <class T>
class d_GeoCollection
{
public:
d_GeoCollection ();
d_GeoCollection (const char* collection_name);
d_GeoCollection (Handle hdCollection);
d_GeoCollection (const d_GeoCollection<T>& coll);
~d_GeoCollection ();
d_GeoCollection& operator= (const d_geoCollection<T>& coll);
void insert_element (const d_Association <d_SpatialKey*, T>& pair);
void remove_element (const d_Association <d_SpatialKey*, T>& pair);
void update_element (const d_Association <d_SpatialKey*, T>& old_pair,
const d_Association <d_SpatialKey*, T>& new_pair);
void insert_elements (const d_Array <d_Association <d_SpatialKey*,
T>>& pairs);
void remove_elements (const d_Array <d_Association <d_SpatialKey*,
T>>& pairs);
d_Bag<T>
d_Bag<T>
d_Bag<T>
d_Bag<T>
contain
intersect
inside
close_to
(const
(const
(const
(const
const
d_SpatialKey& point);
d_SpatialKey& window);
d_SpatialKey& window);
d_SpatialKey& window,
d_Distance distance);
};
O2Spatial User Manual
43
4
O2Spatial C++ API Reference
4.2 Member functions descriptions
Th is sect ion gives t h e fu ll descr ipt ion of t h e followin g C++ m em ber
fu n ct ion s for spat ial in dex m an agem en t :
For d_GeoCollect ion :
• close_t o
• con t ain
• d_GeoCollect ion (con st r u ct or )
• d_GeoCollect ion (con st r u ct or )
• in ser t _elem en t
• in ser t _elem en t s
• in side
• in ter sect
• oper at or =
• r em ove_elem en t
• r em ove_elem en t s
• u pdate_elem en t
For d_Spat ialKey :
• clon e
• d_SpatialKey2D (con st r u ct or )
• d_SpatialKey2D (con st r u ct or )
• d_SpatialKey3D (con st r u ct or )
• d_SpatialKey3D (con st r u ct or )
• dim en sion
• en lar ge
• get In t er n alKey
• get Size
• isAPoin t
• o2_get_n am e
• oper at or =
• oper at or +=
44
O2Spatial User Manual
Member functions descriptions
close_to
Summary
Gets the objects, whose minimum rectangle is within the distance of the
rectangle window (if the window size is equal to zero, it is considered as a
point).
Syntax
d_Bag<T> d_GeoCollection<T>::close_to
(const d_SpatialKey& window, const d_Distance distance);
Arguments
window
distance
Returns
Returns a bag containing the objects found.
Error
Throws a d_Error object (see the ODMG C++ Reference Guide) if the following
error occurs :
Window (rectangle) to be searched.
Distance added to the window which defines the search
space.
• spatial key out of bounds (d_Error::InvalidSpatialKey).
O2Spatial User Manual
45
4
O2Spatial C++ API Reference
contain
46
Summary
Gets the objects, whose minimum rectangle contains the point.
Syntax
d_Bag<T> d_GeoCollection::contain
(const d_SpatialKey& point);
Arguments
point
Returns
Returns a bag containing the objects found.
Error
None.
Zero-surface key to be tested.
O2Spatial User Manual
Member functions descriptions
d_GeoCollection (constructor)
Summary
Opens a collection indexed with a spatial index.
Syntax
d_GeoCollection<T>::d_GeoCollection (Handle hdCollection);
Arguments
hdCollection
Returns
None.
Error
Throws a d_Error object (see the ODMG C++ Reference Guide) if one of the
following errors occur :
Handle to the collection to be opened.
• no database has been opened (d_Error::NoOpenedDatabase),
• no such named collection exists in the current database
(d_Error::NoSuchNamedCollection),
• the collection is not indexed with a spatial index (d_Error::UnknownIndex).
O2Spatial User Manual
47
4
O2Spatial C++ API Reference
d_GeoCollection (constructor)
Summary
Opens a named collection indexed with a spatial index.
Syntax
d_GeoCollection<T>::d_GeoCollection
(const char* CollectionName);
Arguments
CollectionName
Returns
None.
Error
Throws a d_Error object if one of the following errors occurs:
Database name of the collection to be opened.
• no database has been opened (d_Error::NoOpenedDatabase).
• no such named collection exists in the current database.
(d_Error::NoSuchNamedCollection)
• the collection is not indexed with a spatial index. (d_Error::UnknownIndex)
48
O2Spatial User Manual
Member functions descriptions
insert_element
Summary
Inserts an element into the spatial index.
Syntax
void d_GeoCollection<T>::insert_elements
(const d_Association <d_SpatialKey*, T>& pair);
Arguments
pair
Returns
None.
Error
None.
Pair to be inserted within the spatial index.
O2Spatial User Manual
49
4
O2Spatial C++ API Reference
insert_elements
50
Summary
Inserts several elements into the spatial index.
Syntax
void d_GeoCollection<T>::insert_elements
(const d_Array <d_Association <d_SpatialKey*, T>>& pair);
Arguments
pair
Returns
None.
Error
None.
Array pairs to be inserted within the spatial index.
O2Spatial User Manual
Member functions descriptions
inside
Summary
Gets the objects, whose minimum rectangle is strictly included in the rectangle
window.
Syntax
d_Bag <T> d_GeoCollection<T>::inside
(const d_SpatialKey& window);
Arguments
window
Returns
Returns a bag containing the objects found.
Error
None.
Window space to be searched.
O2Spatial User Manual
51
4
O2Spatial C++ API Reference
intersect
52
Summary
Gets the objects, whose minimum rectangle has a non-empty intersection with
the rectangle window.
Syntax
d_Bag <T> d_GeoCollection<T>::intersect
(const d_SpatialKey& window);
Arguments
window
Returns
Returns a bag containing the objects found.
Error
None.
Window space to be searched.
O2Spatial User Manual
Member functions descriptions
operator=
Summary
Assigns a d_GeoCollection object to another.
Syntax
d_GeoCollection& d_GeoCollection<T>::operator=
(const d_GeoCollection& coll);
Arguments
Collection to be opened.
Returns
None.
Error
None.
O2Spatial User Manual
53
4
O2Spatial C++ API Reference
remove_element
54
Summary
Removes an element from the spatial index.
Syntax
void d_GeoCollection<T>::remove_elements
(const d_Association <d_SpatialKey*, T>& pair);
Arguments
pair
Returns
None.
Error
None.
Pair to be removed from the spatial index.
O2Spatial User Manual
Member functions descriptions
remove_elements
Summary
Removes several elements from the spatial index.
Syntax
void d_GeoCollection<T>::remove_elements
(const d_Array <d_Association <d_SpatialKey*, T>>& pair);
Arguments
pair
Returns
None.
Error
None.
Array pairs to be removed from the spatial index.
O2Spatial User Manual
55
4
O2Spatial C++ API Reference
update_element
56
Summary
Updates an element of the spatial index.
Syntax
void d_GeoCollection<T>::update_element
(const d_Association <d_SpatialKey*, T>& old_pair
const d_Association <d_SpatialKey*, T>& new_pair);
Arguments
old_pair
new_pair
Returns
None.
Error
None.
Pair to be updated within the spatial index
New value of the pair to be updated.
O2Spatial User Manual
Member functions descriptions
clone
Summary
Gets a copy of a spatial key, whatever its dimension.
Syntax
d_SpatialKey* d_SpatialKey::clone () const;
Arguments
None.
Returns
A pointer to the key copy of a nil pointer if any error occurred.
Error
If any copy error occurred, returns a nil pointer.
O2Spatial User Manual
57
4
O2Spatial C++ API Reference
d_SpatialKey2D (constructor)
Summary
Builds a zero-surface 2-D spatial key from the corresponding point coordinates.
Syntax
d_SpatialKey2D::d_SpatialKey2D (long x, long y);
Arguments
x, y
Returns
None.
Error
None.
New spatial key coordinates.
.
58
O2Spatial User Manual
Member functions descriptions
d_SpatialKey2D (constructor)
Summary
Builds a 2-D spatial key from the corresponding rectangle coordinates.
Syntax
d_SpatialKey2D::d_SpatialKey2D (long xmin, long ymin,
long xmax, long ymax);
Arguments
xmin, ymin, xmax, ymax
Returns
None.
Error
None.
New spatial key coordinates.
O2Spatial User Manual
59
4
O2Spatial C++ API Reference
d_SpatialKey3D (constructor)
60
Summary
Builds a zero-surface 3-D spatial key from the corresponding point coordinates .
Syntax
d_SpatialKey3D::d_SpatialKey3D (long x, long y, long z);
Arguments
x, y, z
Returns
None.
Error
None.
New spatial key coordinates.
O2Spatial User Manual
Member functions descriptions
d_SpatialKey3D (constructor)
Summary
Builds a 3-D spatial key from the corresponding rectangle coordinates.
Syntax
d_SpatialKey3D::d_SpatialKey3D (long xmin, long ymin,
long zmin, long xmax, long ymax, long zmax);
Arguments
xmin, ymin, zmin, xmax, ymax. zmax
Returns
None.
Error
None.
O2Spatial User Manual
New spatial key coordinates.
61
4
O2Spatial C++ API Reference
dimension
62
Summary
Gets the indexed space dimension (two if two coordinates are required to
describe a point, three if three coordinates are needed, and so on).
Syntax
virtual int d_SpatialKey::dimension () const;
Arguments
None.
Returns
Returns the dimension as an integer.
Error
None.
O2Spatial User Manual
Member functions descriptions
enlarge
Summary
Resizes the spatial key.
Syntax
void d_SpatialKey::enlarge (d_Distance distance);
Arguments
The distance.
Returns
Returns an enlarged key as shown in the following 2-D drawing :
Distance
Old key area
New key area
Distance
Error
None.
.
O2Spatial User Manual
63
4
O2Spatial C++ API Reference
getInternalKey
64
Summary
Gets the internal spatial key structure.
Syntax
const void* d_SpatialKey::getInternalKey () const;
Arguments
None.
Returns
Returns a pointer to the internal spatial key structure.
Error
None.
O2Spatial User Manual
Member functions descriptions
getSize
Su m m ar y
Gets the internal spatial key structure size.
Syntax
int d_SpatialKey::getSize () const;
Arguments
None.
Returns
Returns the size in bytes.
Error
None.
O2Spatial User Manual
65
4
O2Spatial C++ API Reference
isAPoint
66
Summary
Checks whether the spatial key is a point.
Syntax
int d_SpatialKey::isAPoint () const;
Arguments
None.
Returns
Returns TRUE if the spatial key is a zero-surface rectangle, and FALSE
otherwise.
Error
None.
O2Spatial User Manual
Member functions descriptions
o2_get_name
Summary
Gets the key class name used by O2 for its own type verification.
Syntax
const char* d_SpatialKey::o2_get_name () const;
Arguments
None.
Returns
Returns a string which contains the key class name.
Error
None.
O2Spatial User Manual
67
4
O2Spatial C++ API Reference
operator=
68
Summary
Assigns a key to another.
Syntax
d_SpatialKey& d_SpatialKey::operator=
(const d_SpatialKey& key) const;
Arguments
The key to be assigned.
Returns
None.
Error
None.
O2Spatial User Manual
Member functions descriptions
operator+=
Summary
Enlarges a key with the area covered by another key.
Syntax
virtual const d_SpatialKey& d_SpatialKey::operator+=
(const d_SpatialKey&) const;
Arguments
The key to be included.
Returns
Returns an enlarged key as shown in the following 2-D drawing :
Key to be
included
New key
Error
Old key
None.
O2Spatial User Manual
69
4
70
O2Spatial C++ API Reference
O2Spatial User Manual
5
Spatial Indexing with
O2Engine API
5
Th is ch apt er descr ibes t h e u se of spat ial in dexin g wit h t h e
O2 En gin e API.
It con tain s th e followin g sect ion s:
• In t r odu ct ion
• O2 En gin e API : Spat ial In dex
O2Spatial User Manual
71
5
Spatial Indexing with O2Engine API
5.1 Introduction
Th e O 2 En gin e API Spat ial In dex in ter face is m ade u p of a set of
fu n ct ion s th at allow you t o m ain t ain an d access a spat ial in dex of an O2
dat abase.
Th e libr ar y of spatial in dex fu n ct ion s allows t o cr eat e, r em ove, u pdate
an d qu er y t h e spat ial in dex associated wit h a collection of O2 object s.
5.2 O2 Engine API : Spatial Index
Th e spat ial in dex in t er face of t h e O2 En gin e API defin es a collect ion of
oper at ion s available t o t h e developer of O 2 En gin e applicat ion s for
m an agin g a spatial in dex.
Th e com m an ds ar e divided in t o t h r ee cat egor ies of oper at ion s:
1. Th e oper at ion s on t h e spat ial in dex :
• o2x_spatial_index_create
• o2x_spatial_indexed
• o2x_spatial_index_delete
• o2x_spatial_index_reorganize
• o2x_spatial_index_get_info
• o2x_spatial_index_free_descriptor
• o2x_spatial_index_get_collection
2. Th e oper at ion s on t h e elem en t s of th e spatial in dex :
• o2x_spatial_index_insert_key
• o2x_spatial_index_group_insert_key
• o2x_spatial_index_delete_key
• o2x_spatial_index_group_delete_key
• o2x_spatial_index_replace_key
3. Th e sear ch oper at ion s on t h e spatial in dex :
• o2x_spatial_index_scan_open
• o2x_spatial_index_scan_close
• o2x_spatial_index_scan_read
72
O2Spatial User Manual
O2 Engine API : Spatial Index
o2x_spatial_index_create
Summary
Cr eat e a spat ial in dex associat ed wit h a collect ion of per sist en t object s.
Syntax
#include <o2.h>
#include <o2_error.h>
#include <o2_spatialindex.h>
int o2x_spatial_index_create( Handle colHd,
char * volumeName,
void *opaque);
Description
Ver ifies in t h e spat ial in dex cat alogu e t h at th e collect ion in dicat ed by
t h e par am et er colHd h as n ot been pr eviou sly associat ed with a spat ial
in dex.
Cr eat es t h e O2 St or e file for th e spatial in dex t r ee in t h e volu m e declar ed
by t h e par am eter volumeName or in t h e sam e volu m e of t h e collect ion , if
volumeName is set t o zer o.
In it ializes t h e spat ial in dex as a fu n ct ion of t h e par am et er opaque.
Wh en u sin g th e O2 Spat ial in dexin g en gin e, t h e par am et er opaque is
expect ed to be of t ype o2_SiArgList*. Th is class en ables t h e u ser t o set
all t h e spat ial in dex par am et er s as (option , valu e) cou ples.
Th e followin g exam ple sh ows h ow to bu ild su ch an object :
o2_SiArgList argList;
argList.addArgument("IndexType", "RQuadTree");
argList.addArgument("KeyCoordType", "Integer32");
argList.addArgument("Dimension", 2);
Th e ar gu m en t s, wh ich m u st be set by u sin g an o2_SiArgList object ,
in clu de t h ose descr ibed in sect ion 3.5. Th e ar gu m en t s ar e descr ibed
below :
O2Spatial User Manual
73
5
Spatial Indexing with O2Engine API
Option
Type
Description
Recommended value
IndexType
string
Name of the spatial index algorithm.
Must be “RQuadTree” to use the
O 2Spatial indexing algorithm.
RQuadTree
Dimension
integer
Number of coordinates of the indexed
space.
2
OnlyPoints
boolean
True if indexed objects are always points.
False
KeyCoordType
string
Type used for spatial key coordinates.
Must be "Integer16" or "Integer32".
Integer32
Dd_Min
KeyCoordType
value
Minimum coordinate value for the given
dimension d (used for internal coordinates scaling optimization).
KeyCoordType
minimum value
Dd_Max
KeyCoordType
value
Maximum coordinate value for the given
dimension d (used for internal coordinates scaling optimization).
KeyCoordType
maximum value
Dd_Min
RegionSize
integer
Minimum size of an indexed region (in
KeyCoordType-based coordinates) for
dimension d. Such a region will not be
segmented more
2
MaxChildren
integer
Maximum number of subspaces generated each time a given indexed space
needs to be segmented (used when a
R-QuadTree node is saturated)
2Dimension
Threshold
integer
Number of (key, values) couples in each
R-QuadTree node. Must be greater or
equal to 2, and less or equal than :
Highest possible value (see
description)
- 167 if KeyCoordType= integer 32
Dimension = 2
- 126 if KeyCoordType=Integer 32
Dimension=3
At t h is level of pr ogr am m in g n o defau lt valu e is pr ovided for t h ese
par am et er s. An appr opr iate valu e m u st t h en be set u p for all of t h em .
Returns
O2_OK if su ccessfu l, er r or code oth er wise.
Errors
O2E_NOTSUPPORTED
Th e fu n ct ion is n ot im plem en t ed.
O2E_SIMALGO
Er r or in Spat ial In dex M odu le algor it h m .
74
O2Spatial User Manual
O2 Engine API : Spatial Index
O2E_PARAMETER
Th e par am eter opaque is in cor r ect .
O2E_INVALIDCOLLECTION
Th e h an dle colHd is in valid or is n ot a h an dle t o a
per sisten t collect ion .
O2E_IS_INDEXED
Th er e is n o spatial in dex for t h is collect ion .
O2E_NOSPACEONDISK
No m or e space on disk .
O2E_PERMISSIONDENIED
Th e h an dle colHd is valid, bu t n o spat ial in dex can be
cr eat ed on a collect ion of ver sion n ed objects.
O2E_ERROR
In t er n al er r or .
Sample
int create_spidx (Handle
o2_Boolean
{
o2_SiArgList
SIOptions;
hdCollection,
indexOnlyContainsPoints)
SIOptions.addArgument ("IndexType",
"RQuadTree");
SIOptions.addArgument ("KeyCoordType", "Integer32");
SIOptions.addArgument ("Dimension",
2);
SIOptions.addArgument ("D1_Min",
0);
SIOptions.addArgument ("D2_Min",
0);
SIOptions.addArgument ("D1_Max",
40000);
SIOptions.addArgument ("D2_Max",
40000);
SIOptions.addArgument ("D1_MinRegionSize",
2);
SIOptions.addArgument ("D2_MinRegionSize",
2);
SIOptions.addArgument ("MaxChildren",
4);
SIOptions.addArgument ("Threshold",
167);
SIOptions.addArgument ("OnlyPoints",
indexOnlyContainsPoints);
return o2x_spatial_index_create (hdCollection, 0, (void*)
&SIOptions);
}
O2Spatial User Manual
75
5
Spatial Indexing with O2Engine API
o2x_spatial_indexed
Summary
Ret u r n s a h an dle t o t h e spatial in dex associat ed wit h a collect ion of
per sist en t object s.
Syntax
#include <o2.h>
#include <o2_error.h>
#include <o2_spatialindex.h>
int o2x_spatial_indexed( Handle colHd,
o2x_SpatialIndexDesc **idxDesc);
Description
Sear ch es for t h e spat ial in dex associat ed wit h a collect ion iden t ified by
colHd in t h e spat ial in dex cat alogu e.
If th e cor r espon din g en t r y exist s, a h an dle for th e spatial in dex is
cr eated an d it s valu e is assign ed t o th e par am et er idxDesc.
Ot h er wise t h e valu e NULL is assign ed t o t h e par am et er idxDesc.
Th e spatial in dex descr ipt or cr eat ed by t h e o2x_spatial_indexed
fu n ction sh ou ld always be deleted u sin g t h e
o2x_spatial_index_free_descriptor fu n ct ion .
Returns
O2_OK if su ccessfu l, er r or code oth er wise.
Errors
O2E_PARAMETER
Th e par am et er colHd or idxDesc is in cor r ect .
O2E_NOTINDEXED
Th er e is n o spat ial in dex for t h is collect ion .
O2E_INVALID_COLLECTION
Th e h an dle colHd is in valid or is n ot a h an dle to a
per sisten t collect ion .
76
O2Spatial User Manual
O2 Engine API : Spatial Index
o2x_spatial_index_delete
Summary
Rem ove a spat ial in dex associated wit h a collect ion of per sist en t object s.
Syntax
#include <o2_error.h>
#include <o2_spatialindex.h>
int o2x_spatial_index_delete(
o2x_SpatialIndexDesc *idxDesc);
Description
Delet es t h e spat ial in dex iden t ified by t h e par am et er idxDesc, an d
r em oves th e cor r espon din g en t r y in th e spat ial in dex cat alogu e.
Th e oper at ion is n ot execu t ed if t h er e exist s a scan oper at ion r u n n in g
at t h e tim e of t h e call.
Returns
O2_OK if su ccessfu l, er r or code ot h er wise.
Errors
O2E_SIMALGO
Er r or in Spat ial In dex M odu le algor it h m .
O2E_PARAMETER
Th e par am eter idxDesc is in cor r ect
O2E_ILLEGALCALL
Fu n ct ion was called du r in g a scan .
O2Spatial User Manual
77
5
Spatial Indexing with O2Engine API
o2x_spatial_index_reorganize
Summary
Reor gan ize th e dist r ibu tion of in dex n odes on a disk page.
Syntax
#include <o2_error.h>
#include <o2_spatialindex.h>
int o2x_spatial_index_reorganize(
o2x_SpatialIndexDesc *idxDesc);
Description
Th e fu n ct ion o2x_spatial_index_reorganize gat h er s t h e spat ial
in dex n odes on a disk page so as t o r edu ce t h e access t im e du r in g a
sear ch of t h e in dex t r ee.
Th is fu n ct ion fails if a scan oper at ion is act ive on t h e spat ial in dex.
Returns
O2_OK if su ccessfu l, er r or code oth er wise.
Errors
O2E_NOTSUPPORTED
Th e fu n ct ion is n ot im plem en t ed.
O2E_SIMALGO
Er r or in Spat ial In dex M odu le algor it h m .
O2E_PARAMETER
Th e par am et er idxDesc is in cor r ect .
O2E_ILLEGALCALL
Fu n ct ion was called du r in g a scan .
O2E_NOSPACEONDISK
No m or e space on disk .
78
O2Spatial User Manual
O2 Engine API : Spatial Index
o2x_spatial_index_get_info
Summary
Collect s in for m at ion on t h e spat ial in dex.
Syntax
#include <o2_error.h>
#include <o2_spatialindex.h>
int o2x_spatial_index_get_info(
o2x_SpatialIndexDesc *idxDesc,
o2x_SpatialIndexInfo *idxInfo);
Description
Pr ovides t h e r equ est ed in for m at ion for th e str u ct u r e idxInfo.
Th is fu n ct ion r et u r n s st at ist ical in for m ation on t h e spat ial in dex,
accor din g to t h e bit m ask pr ovided in th e st r u ctu r e idxInfo.
Th e t ype o2x_SpatialIndexInfo is defin ed as follows:
typedef struct {
unsigned int
mask;
int
dimension;
int
depth;
int
entryCount;
int
allNodeCount;
int
nodeCount;
double
nodeMeanFillFactor;
int
leafCount;
int
emptyLeafCount;
double
leafMeanFillFactor;
} o2x_SpatialIndexInfo;
Th e valu es wh ich can be u sed to set th e bit m ask mask ar e as follows :
O2X_SI_DIMENSION,
O2X_SI_DEPTH,
O2X_SI_ENTRYCNT,
O2X_SI_ALLNODECNT,
O2X_SI_NODEMFF,
O2X_SI_LEAFCNT,
O2X_SI_EMPTYLEAFCNT,
O2X_SI_LEAFMFF
• If mask & O2X_SI_DIMENSION is TRUE, dimension con tain s th e dim en sion of t h e spat ial in dex.
• If mask & O2X_SI_DEPTH is TRUE, depth con t ain s t h e dept h of t h e spatial in dex t r ee.
O2Spatial User Manual
79
5
Spatial Indexing with O2Engine API
• If mask & O2X_SI_ENTRYCNT is TRUE, entryCount con t ain s t h e n u m ber
of en t r ies (key, element) in t h e spat ial in dex t r ee. Note t h at t h e n u m ber
of spat ial in dex en tr ies m ay be gr eater t h an t h e n u m ber of object s r eally
in ser t ed in t h e in dex, sin ce som e object s m ay belon g to sever al qu adr an t s.
• If mask & O2X_SI_ALLNODECNT is TRUE, allNodeCount con t ain s t h e
t otal n u m ber of n odes in t h e spat ial in dex t r ee.
• If mask & O2X_SI_NODECNT is TRUE, nodeCount con t ain s t h e n u m ber of
in t er m ediar y n odes in t h e spat ial in dex tr ee in clu din g t h e r oot n ode.
• If mask & O2X_SI_NODEMFF is TRUE, nodeMeanFillFactor con t ain s t h e
per cen t age of occu pied in ter m ediar y n odes in t h e spat ial in dex tr ee.
• If mask & O2X_SI_LEAFCNT is TRUE, leafCount con t ain s t h e n u m ber of
leaf n odes in t h e spat ial in dex t r ee.
• If mask & O2X_SI_EMPTYLEAFCNT is TRUE, emptyLeafCount con t ain s
t h e n u m ber of em pt y leaf n odes in th e spatial in dex t r ee.
• If mask & O2X_SI_LEAFMFF is TRUE, leafMeanFillFactor con t ain s t h e
per cen t age of occu pied leaf n odes in t h e spat ial in dex t r ee.
Th e per cen t age of occu pied leaves is distin gu ish ed fr om t h e per cen t age
of occu pied in t er m ediar y n odes in t h at leaves an d n odes can con t ain
differ en t m axim u m n u m ber s of k eys. M or eover , t h e n ot ion of an em pt y
leaf m ay n ot be sign ifican t for cer t ain spat ial in dex algor it h m s.
Returns
O2_OK if su ccessfu l, er r or code oth er wise.
Errors
O2E_NOTSUPPORTED
Th e fu n ct ion is n ot im plem en t ed.
O2E_SIMALGO
Er r or in Spat ial In dex M odu le algor it h m .
O2E_ILLEGALOP
Th e par am et er idxDesc or idxInfo is in cor r ect .
80
O2Spatial User Manual
O2 Engine API : Spatial Index
o2x_spatial_index_free_descriptor
Summary
Fr ee th e m em or y u sed by a spat ial in dex descr iptor .
Syntax
#include <o2_error.h>
#include <o2_spatialindex.h>
int o2x_spatial_index_free_descriptor(
o2x_SpatialIndexDesc** idxDesc);
Description
Fr ee t h e m em or y associat ed wit h t h e spatial in dex descr ipt or cr eat ed by
o2x_spatial_indexed. Ever y spat ial in dex descr ipt or sh ou ld be fr eed
by o2x_spatial_index_free_descriptor.
After a call t o o2x_spatial_index_free_descriptor a spat ial
descr ipt or is always NULL.
Returns
O2_OK if su ccessfu l, er r or code ot h er wise.
Errors
O2E_PARAMETER
Th e spat ial in dex descr ipt or idxDesc is in cor r ect .
O2Spatial User Manual
81
5
Spatial Indexing with O2Engine API
o2x_spatial_index_get_collection
82
Summary
Ret u r n th e h an dle of t h e in dexed collection .
Syntax
#include <o2.h>
#include <o2_error.h>
#include <o2_spatialindex.h>
Handle o2x_spatial_index_get_collection(
o2x_SpatialIndexDesc* idxDesc);
Description
Ret u r n th e h an dle of t h e collect ion of per sist en t object s associat ed with
t h e spat ial in dex iden tified by idxDesc.
Returns
A valid collection h an dle if su ccessfu l, a NULL h an dle oth er wise.
O2Spatial User Manual
O2 Engine API : Spatial Index
o2x_spatial_index_insert_key
Summary
In ser t a n ew en t r y in t h e spat ial in dex.
Syntax
#include <o2.h>
#include <o2_error.h>
#include <o2_spatialindex.h>
int o2x_spatial_index_insert_key(
o2x_SpatialIndexDesc *idxDesc,
int keyLength, void *key,
Handle element);
Description
In ser t s an en t r y (key, element) in t o t h e spat ial in dex.
Th e spat ial k ey is passed by t h e par am et er key wh ich pr ovides t h e valu e
an d t h e par am et er keyLength wh ich pr ovides th e len gt h . Th e t ype of
k ey is n ot defin ed at th e level of t h e O 2 En gin e an d O2 Stor e. Th e spat ial
in dexin g m odu le pr ovides th e str u ct u r e of t h e k ey wh en n eeded at t h e
level of t h e applicat ion .
Wh en u sin g th e stan dar d O2 Spat ial in dexin g en gin e, t h e k ey is expect ed
t o be a poin t er t o a SiBoundingBox object , an d keyLength sh ou ld be
equ al t o zer o.
Th e par am et er element is a h an dle of t h e O 2 object t o be in dexed.
Th is fu n ct ion fails if a scan oper at ion is act ive on t h e spat ial in dex.
Returns
O2_OK if su ccessfu l, er r or code ot h er wise.
Errors
O2E_NOTSUPPORTED
Th e fu n ct ion is n ot im plem en t ed.
O2E_SIMALGO
Er r or in Spat ial In dex M odu le algor it h m .
O2E_ILLEGALCALL
Fu n ct ion was called du r in g a scan .
O2E_PARAMETER
Th e par am eter idxDesc or key or element is in cor r ect .
O2E_KEYALREADYEXISTS
Th e cou ple (key, element) alr eady exist s in t h e in dex.
O2E_NOSPACEONDISK
No m or e space on disk .
O2Spatial User Manual
83
5
See Also
84
Spatial Indexing with O2Engine API
o2x_spatial_index_group_insert_key()
o2x_spatial_index_delete_key()
o2x_spatial_index_group_delete_key()
o2x_spatial_index_replace_key()
O2Spatial User Manual
O2 Engine API : Spatial Index
o2x_spatial_index_group_insert_key
Summary
In ser t m u lt iple n ew en t r ies in th e spat ial in dex.
Syntax
#include <o2.h>
#include <o2_error.h>
#include <o2_spatialindex.h>
int o2x_spatial_index_group_insert_key(
o2x_SpatialIndexDesc *idxDesc,
int card, int keyLength,
void **keyArray, Handle *eltArray);
Description
In ser t s m u lt iple en t r ies (key[i], eltArray[i] wit h i var yin g bet ween
[0, card-1]) in t o t h e spat ial in dex, wit h m in im izat ion of t h e t r aver sal of
t h e spat ial in dex t r ee.
Th e par am et er keyLength gives t h e len gt h of a sin gle k ey. Th er e is n o
defin it ion of th e k ey t ype in th e O2 En gin e an d O2 St or e. Th e spat ial
in dexin g m odu le pr ovides th e str u ct u r e of t h e k ey for t h e applicat ion
wh en n eeded.
Wh en u sin g th e stan dar d O 2 Spat ial in dexin g en gin e, keyArray is
expect ed to be an ar r ay of poin t er s to SiBoundingBox object s, an d
keyLength sh ou ld be equ al t o zer o.
Th is fu n ct ion fails if a scan oper at ion is act ive on t h e spat ial in dex.
Returns
O2_OK if su ccessfu l, er r or code ot h er wise.
Errors
O2E_NOTSUPPORTED
Th e fu n ct ion is n ot im plem en t ed.
O2E_SIMALGO
Er r or in Spat ial In dex M odu le algor it h m .
O2E_ILLEGALCALL
Fu n ct ion was called du r in g a scan .
O2E_PARAMETER
Th e par am eter idxDesc or keyArray or eltArray is
in cor r ect .
O2E_NOSPACEONDISK
No m or e space on disk .
See Also
o2x_spatial_index_insert_key()
o2x_spatial_index_delete_key()
o2x_spatial_index_group_delete_key()
o2x_spatial_index_replace_key()
O2Spatial User Manual
85
5
Spatial Indexing with O2Engine API
o2x_spatial_index_delete_key
Summary
Rem ove an en tr y fr om t h e spat ial in dex.
Syntax
#include <o2.h>
#include <o2_error.h>
#include <o2_spatialindex.h>
int o2x_spatial_index_delete_key(
o2x_SpatialIndexDesc *idxDesc,
int keyLength, void *key,
Handle *element);
Description
Rem oves t h e cou ple (key, element) fr om th e spatial in dex.
Th e spat ial k ey is passed by th e par am et er key wh ich pr ovides th e valu e
an d th e par am et er keyLength wh ich pr ovides t h e len gt h . Th e t ype of
k ey is n ot defin ed at t h e level of t h e O 2 En gin e an d O2 St or e. Th e spat ial
in dexin g m odu le pr ovides th e st r u ctu r e of t h e k ey wh en n eeded at an
applicat ion level.
Wh en u sing t h e stan dar d O2 Spat ial in dexin g en gin e, t h e k ey is expect ed
t o be a poin ter t o a SiBoundingBox object , an d keyLength sh ou ld be
equ al t o zer o.
Th e par am et er element is a h an dle for t h e O 2 in dexed object .
Th is fu n ct ion fails if a scan oper at ion is act ive on t h e spat ial in dex.
Returns
O2_OK if su ccessfu l, er r or code oth er wise.
Errors
O2E_NOTSUPPORTED
Th e fu n ct ion is n ot im plem en t ed.
O2E_SIMALGO
Er r or in Spat ial In dex M odu le algor it h m .
O2E_ILLEGALCALL
Fu n ct ion was called du r in g a scan .
O2E_PARAMETER
Th e par am et er idxDesc or key or element is in cor r ect .
O2E_KEYNOTFOUND
Th e cou ple (key, element) alr eady exist s in t h e in dex.
See Also
86
o2x_spatial_index_insert_key()
o2x_spatial_index_group_insert_key()
o2x_spatial_index_delete_key()
o2x_spatial_index_replace_key()
O2Spatial User Manual
O2 Engine API : Spatial Index
o2x_spatial_index_group_delete_key
Summary
Rem ove m u ltiple en t r ies fr om t h e spat ial in dex.
Syntax
#include <o2.h>
#include <o2_error.h>
#include <o2_spatialindex.h>
int o2x_spatial_index_goupr_delete_key(
o2x_SpatialIndexDesc *idxDesc,
int card, int keyLength,
void **key, Handle *eltArray);
Description
Rem oves m u lt iple en t r ies (key[i], eltArray[i] wit h i var yin g bet ween
[0, card-1]) fr om t h e spat ial in dex, wit h m in im izat ion of t h e t r aver sal of
t h e spat ial in dex t r ee.
Th e par am et er keyLength gives t h e len gt h of a sin gle k ey. Th er e is n o
defin it ion of th e k ey t ype in th e O2 En gin e an d O2 St or e. Th e spat ial
in dexin g m odu le pr ovides th e str u ct u r e of t h e k ey for t h e applicat ion
wh en n eeded.
Wh en u sin g th e stan dar d O 2 Spat ial in dexin g en gin e, keyArray is
expect ed to be an ar r ay of poin t er s to SiBoundingBox object s, an d
keyLength sh ou ld be equ al t o zer o.
Th is fu n ct ion fails if a scan oper at ion is act ive on t h e spat ial in dex.
Returns
O2_OK if su ccessfu l, er r or code ot h er wise.
Errors
O2E_NOTSUPPORTED
Th e fu n ct ion is n ot im plem en t ed.
O2E_SIMALGO
Er r or in Spat ial In dex M odu le algor it h m .
O2E_ILLEGALCALL
Fu n ct ion was called du r in g a scan .
O2E_PARAMETER
Th e par am eter idxDesc or keyArray or eltArray is
in cor r ect
O2E_NOSPACEONDISK
No m or e space on disk .
See Also
o2x_spatial_index_insert_key()
o2x_spatial_index_group_insert_key()
o2x_spatial_index_delete_key()
o2x_spatial_index_replace_key()
O2Spatial User Manual
87
5
Spatial Indexing with O2Engine API
o2x_spatial_index_replace_key
Summary
Su bst it u t e on e en t r y wit h an ot h er en tr y in t h e spat ial in dex.
Syntax
#include <o2.h>
#include <o2_error.h>
#include <o2_spatialindex.h>
int o2x_spatial_index_replace_key(
o2x_SpatialIndexDesc *idxDesc,
int keyLength, void *key,
Handle oldEltHd, Handle newEltHd);
Description
Su bst it u t es t h e cou ple (key, oldEltHd) by th e cou ple (key, newEltHd) in
t h e spat ial in dex.
Th e spatial k ey is passed by t h e par am et er key wh ich pr ovides t h e
valu e an d t h e par am et er keyLength wh ich pr ovides t h e len gt h . Th e
t ype of k ey is n ot defin ed at t h e level of t h e O 2 En gin e an d O2 St or e. Th e
spat ial in dexin g m odu le pr ovides t h e st r u ctu r e of t h e k ey wh en n eeded
at an application level.
Wh en u sing t h e stan dar d O2 Spat ial in dexin g en gin e, t h e k ey is expect ed
t o be a poin ter t o a SiBoundingBox object , an d keyLength sh ou ld be
equ al t o zer o.
Th e par am et er s oldEltHd an d newEltHd ar e h an dles for O2 object s.
Th is fu n ct ion can execu t e if a scan oper ation is act ive on t h e spat ial
in dex.
Returns
O2_OK if su ccessfu l, er r or code oth er wise.
Errors
O2E_NOTSUPPORTED
Th e fu n ct ion is n ot im plem en t ed.
O2E_SIMALGO
Er r or in Spat ial In dex M odu le algor it h m .
O2E_PARAMETER
Th e par am et er idxDesc or key or oldEltHd or newEltHd
is in cor r ect .
O2E_KEYNOTFOUND
Th e cou ple (key, oldEltHd) does n ot exist in t h e in dex.
O2E_KEYALREADYEXISTS
Th e cou ple (key, newEltHd) alr eady exist s in t h e in dex.
88
O2Spatial User Manual
O2 Engine API : Spatial Index
O2E_NOSPACEONDISK
No m or e space on disk .
O2Spatial User Manual
89
5
Spatial Indexing with O2Engine API
o2x_spatial_index_scan_open
Summary
St ar t a sear ch oper at ion on t h e spat ial in dex.
Syntax
#include <o2_error.h>
#include <o2_spatialindex.h>
int o2x_spatial_index_scan_open(
o2x_SpatialIndexDesc *idxDesc,
int operation, int areaLength,
void *areaValue,
o2x_SpatialIndexScan **idxScan);
Description
In it ializes a scan on t h e spat ial in dex iden t ified by idxDesc an d r et u r n s
an ext er n al iden t ifier for it as t h e var iable idxScan.
Th e par am et er s operation, areaLength an d areaValue defin e t h e
spat ial pr edicate wh ich is applied t o filt er t h e en t r ies r et u r n ed by t h e
fu n ction o2x_spatial_index_scan_read.
Th e available spat ial oper at ion s ar e defin ed by a code at t h e applicat ion
level. Th is code is t r an sfer r ed by t h e par am et er operation.
Wh en u sin g t h e O2 Spat ial in dexin g en gin e, t h e possible valu es for t h e
par am et er s operation an d areaValue ar e as follows :
90
Operation parameter
Meaning
areaValue parameter
O2X_CONTAIN
Retrieve all the
objects which contain a given point.
A pointer to a
SiBoundingBox object
wh ich contains th e
requ ested point.
O2X_INTERSECT
Retrieve all the
objects which intersect a given rectangle
A pointer to a
SiBoundingBox object
wh ich contains th e
requ ested rectangle
O2X_IS_CONTAINED
Retrieve all the
objects which are
in side a given rectangle
O2X_ELLIPSE
Retrieve all the
objects which intersect a given ellipse
O2X_ELLIPSE_
STRICT
Retrieve all the
objects which are
in side a given ellipse
O2Spatial User Manual
A pointer to a SiEllipse object which
contains the requ ested
ellipse.
O2 Engine API : Spatial Index
Returns
Operation parameter
Meaning
areaValue parameter
O2X_POLYGON
Retrieve all the
objects wh ich intersect a given polygon.
O2X_POLYGON_
STRICT
Retrieve all the
objects, wh ich ar e
inside a given polygon
A poin ter to a SiPolygon object which contains th e list of th e
requ ested polygon vertices.
O2X_POLYLINE
Retrieve all the
objects wh ich intersect a given polylin e
A poin ter to a
SiPolyline object
which contains th e list
of the requ ested
polyline ver tices.
O2_OK
if su ccessfu l, er r or code ot h er wise.
Errors
O2E_SIMALGO
Er r or in Spat ial In dex M odu le algor it h m .
O2E_PARAMETER
Th e par am et er idxDesc, operation or areaValue is
in cor r ect .
Samples
SiBoundingBox requestedPoint(x, y, x+1, y+1);
if (o2x_spatial_index_scan_open (
idxDesc,
(int) O2X_CONTAIN,
sizeof (SiBoundingBox *),
&requestedPoint,
&idxScan) !=O2_OK) {
return-1;
//Error;
}
O2Spatial User Manual
91
5
Spatial Indexing with O2Engine API
Si3DPoint center(x, y);
SiEllipse requestedEllipse(center, xRadius, yRadius);
if (o2x_spatial_index_scan_open (
(idxDesc,
(int) O2X_ELLIPSE,
sizeof (SiEllipse*)
&requestedEllipse,
&idxScan)
!=O2_OK)
return -1;
}
Si3DPoint* pointArray=...;
SiPolyline requestedPolyline(numPoints, pointArray);
if (o2x_spatial_index_scan_open (
idxDesc,
(int) O2X_POLYLINE,
sizeof (SiPolyline*)
&requestedPolyline,
&idxScan) !=O2_OK) {
return -1;
}
See Also
92
o2x_spatial_index_scan_close()
o2x_spatial_index_scan_read()
O2Spatial User Manual
O2 Engine API : Spatial Index
o2x_spatial_index_scan_close
Summary
Close a sear ch oper at ion on t h e spat ial in dex.
Syntax
#include <o2_error.h>
#include <o2_spatialindex.h>
int o2x_spatial_index_scan_close(
o2x_SpatialIndexScan **idxScan);
Description
Liber at es t h e cu r sor of t h e scan idxScan.
Returns
O2_OK if su ccessfu l, er r or code ot h er wise.
Errors
O2E_SIMALGO
Er r or in Spat ial In dex M odu le algor it h m .
O2E_PARAMETER
Th e par am eter idxScan is in cor r ect .
O2E_BADSCANID
Th e par am eter idxScan does n ot exist .
See Also
o2x_spatial_index_scan_open()
o2x_spatial_index_scan_read()
O2Spatial User Manual
93
5
Spatial Indexing with O2Engine API
o2x_spatial_index_scan_read
Summary
Ret u r n th e n ext elem en t of t h e spat ial in dex wh ich sat isfies t h e
oper at ion of t h e cu r r en t spat ial scan .
Syntax
#include <o2_error.h>
#include <o2_spatialindex.h>
int o2x_spatial_index_scan_read(
o2x_SpatialIndexScan *idxScan,
o2x_ScanDirection direction,
Handle *hd);
Description
Moves th e scan cu r sor for war d if t h e par am et er direction is set t o
O2X_NEXT or back war d if direction is set t o O2X_PREVIOUS, an d
r et u r n s in t h e par am et er hd a h an dle to an in dexed object poin t ed to by
t h e scan cu r sor .
An y ot h er valu e for th e par am et er direction is in cor r ect .
Returns
O2_OK if su ccessfu l, oth er wise an er r or code; n ot ably O2E_KEYNOTFOUND
wh ich sign ifies t h at t h er e ar e n o m or e en t r ies t o r ecover .
Errors
O2E_NOTSUPPORTED
Th e fu n ct ion is n ot im plem en t ed.
O2E_SIMALGO
Er r or in Spat ial In dex M odu le algor it h m .
O2E_PARAMETER
Th e par am et er idxScan or direction or hd is in cor r ect
O2E_BADSCANID
Th e par am et er idxScan does n ot exist .
O2E_KEYNOTFOUND
No m or e accessible en tr ies.
See Also
94
o2x_spatial_index_scan_open()
o2x_spatial_index_scan_close()
O2Spatial User Manual
INDEX
O2Spatial User Manual
95
INDEX
A
axis 34
B
Bou n din g box 15, 31
C
C 11
C++ In t er face 11
class
d_GeoCollection 43
d_SpatialKey 40
d_SpatialKey2D 41
d_SpatialKey3D 42
close_t o 31
close_to 33, 35, 35
con t ain 30
contain 32, 35, 35
cr eat e spat ial in dex
options 23
d_Dat abase
set _defau lt _vol 57, 62
d_Dictionary 25
d_GeoCollection
close_to 45
constructor 47, 48
contain 46
insert_element 27
insert_elements 49, 50
inside 51
intersect 52
remove_element 27
remove_elements 54, 55
update_element 56
d_GeoCollection 15, 26
d_Spat ialKey 26
clone 57
dimension 62
enlarge 63
getInternalKey 64
getSize 65
isAPoint 66
o2_get_name 67
operator+= 69
operator= 68
d_SpatialKey 15
d_Spat ialKey2D
constructor 58, 59
d_SpatialKey2D 26
d_Spat ialKey3D
constructor 60, 61
d_SpatialKey3D 26
Dd_Min Region Size 30, 74
delete spatial index 23
dist an ce 34
create spatial index 23
F
D
fu ll t ext in dex (FTI) 14
d_Association 25, 26
96
O2Spatial User Manual
INDEX
G
O
getSpatialKey 25
gr aph ical coor din at es 12
O 2 Ar ch it ect u r e 10
o2_set_GeoEllipse 27
O 2 C 11
O 2 Cor ba 11
O 2 DBAccess 11
O 2 En gin e 10
O 2 Gr aph 11
O 2 Kit 11
O 2 Look 11
O 2 OD BC 11
O 2 Stor e 10
O 2 Tools 11
O 2 Web 11
Opt ion
Dd_Max 24, 30, 74
Dd_Min 24, 30, 74
Dim en sion 24, 30, 74
In dexType 24, 30, 73
KeyCoor dType 24, 29, 30, 74
On lyPoin t s 30, 74
I
in clu de file 18
in it ializat ion of sch em a 18
in side 30
inside 33, 35, 35
in t er sect 30
intersect 32, 35, 35
J
opt ion s
create spatial index 23
J ava 11
L
options 23
OQL 11
R
Libr ar y 18
r ect an gle 34
R-Qu adt r ee 15, 23, 29
O2Spatial User Manual
97
INDEX
S
Spat ial k eys 12
SpatialIndexInfo 79
Syst em Ar ch it ect u r e 10
98
O2Spatial User Manual