Download O2 Spatial User Manual
Transcript
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