Home

O2 Spatial User Manual

Contents

1. 14 Setting Up O2Spatial 17 4 2 i LOS SL 2 SR RER RP Re 18 Sebhema miala O oeren 18 Using O2Spatial 21 3 1 Spatial index creation and deletion ccccssseeeeeees 23 The creation and delete serrer 23 Spatial mdex IOUS ecnin 23 3 2 C Interface to a spatial index ccccccesseesseeeeeeeeeseeeeneeeeeees 25 3 3 Spatial Index CONSIPLICIOr rnsnesasannnnnnnnenaannannannninanes 27 3 4 Spatial Index update is smsssananinnnmnednenananastaaanns 27 Insertion and removal methods hisser 27 Udane aan eniooe 29 3 5 Spatial index TUNIS sde visas 29 The O2 spatial index options men een 29 36 GU Nn 30 Typer oi GUTES iad E TO 30 nn ee ee ees 31 Spatial guery examples innen anaa 31 Spatial predicate pararneters seiicieississcisisianversacieaceasastdesnsinderadeionads 34 How teguery spatially eisiea nN nb ads 34 Using object methodi scuaine een 34 Using OQL predicate Sicinius iaiki 35 S TEE A E T E N E A 36 O Spatial User Manual TABLE OF CONTENTS O2Spatial C API Reference 41 Class CST GING nomin s 4 2 Member functions descriptions ccccceeesseeeeeeeeeeeeeeees sd ont oo A a dat ti dr in d GesCollection CONSUUCLOP sister d_GeoCollection constructor oe ceceesessececececeeeessssaeeeeeceens VET Tee TUE ARR PER ES A te sert SSIS orien NES E E CE E E E lo ui Di LE Cos 8 E E A E E E A in en ae Bie eee eee remove SCIEN pair ae
2. O2Web BRNE Figure 1 1 O2 System Architecture The Oo system can be viewed as consisting of three components The Database Engine provides all the features of a Database system and an object oriented system This engine is accessed with Development Tools such as various programming languages O gt development tools and any standard development tool Numerous External Interfaces are provided All encompassing Oo is a versatile portable distributed high performance dynamic object oriented database system Database Engine e OoStore e OoEngine The database management system provides low level facilities through OoStore API to access and manage a database disk volumes files records indices and transactions The object database engine provides direct control of schemas classes objects and transactions through O2Engine API It provides full text indexing and search capabilities with Oz2Search and spatial indexing and retrieval capabilities with OoSpatial It includes a Notification manager for informing other clients connected to the same Oo server that an event has occurred a Version manager for handling multiple object versions and a Replication API for synchronizing multiple copies of an O2 system 10 O Spatial User Manual System overview Programming Languages O2 objects may be created and managed using the following programming languages utilizing all the feat
3. O Spatial User Manual Release 5 0 April 1998 Information in this document is subject to change without notice and should not be construed as a commitment by Ox Technology The software described in this document is delivered under a license or nondisclosure agreement The software can only be used or copied in accordance with the terms of the agreement It is against the law to copy this software to magnetic tape disk or any other medium for any purpose other than the purchaser s own use Copyright 1992 1998 O2 Technology All rights reserved No part of this publication can be reproduced stored in a retrieval system or transmitted in any form or by any means electronic mechanical photocopy without prior written permission of O2 Technology O2 O2Engine API O2C O2DBAccess Oz2Engine OGraph Ookit O2Look OoStore OzTools and O Web are registered trademarks of O2 Technology SQL and AIX are registered trademarks of International Business Machines Corporation Sun SunOS and SOLARIS are registered trademarks of Sun Microsystems Inc X Window System is a registered trademark of the Massachusetts Institute of Technology Unix is a registered trademark of Unix System Laboratories Inc HPUX is a registered trademark of Hewlett Packard Company BOSX is a registered trademark of Bull S A IRIX is a registered trademark of Siemens Nixdorf A G NeXTStep is a registered trademark
4. 02x_spatial_index_reorganize Summary Syntax Description Returns Errors Reorganize the distribution of index nodes on a disk page include lt o2_error h gt include lt o2_spatialindex h gt int o2x_spatial_index_reorganize o2x_SpatialIndexDesc idxDesc The function 02x spatial index reorganize gathers the spatia index nodes on a disk page so as to reduce the access time during a search of the index tree This function fails if a scan operation is active on the spatial index 02_ OK if successful error code otherwise O2E_NOTSUPPORTED The function is not implemented O2E_SIMALGO Error in Spatial Index Module algorithm O2E_PARAMETER The parameter idxDesc is incorrect O2E_ILLEGALCALL Function was called during a scan O2E_NOSPACEONDISK No more space on disk 78 O Spatial User Manual O2 Engine API Spatial Index 02x_spatial_index_get_info Summary Syntax Description Collects information on the spatial index include lt o2_error h gt include lt o2_spatialindex h gt int o2x_spatial_index_get_info o2x_SpatialIndexDesc idxDesc o2x_SpatialIndexInfo idxInfo Provides the requested information for the structure idxInfo This function returns statistical information on the spatial index according to the bit mask provided in the structure idxInfo The type 0o2x_SpatialIndexInfo is defined as follows typedef struct unsigned int mask int dime
5. O2Spatial C API Reference update element Summary Syntax Arguments Returns Error Updates an element of the spatial index void d GeoCollection lt T gt update element const d_ Association lt d_SpatialKey T gt amp old pair const d_ Association lt d SpatialkKey T gt amp new pair old pair Pair to be updated within the spatial index new pair New value of the pair to be updated None None 56 O Spatial User Manual Member functions descriptions clone Summary Syntax Arguments Returns Error Gets a copy of a spatial key whatever its dimension d_SpatialKey d_SpatialKey clone const None A pointer to the key copy of a nil pointer if any error occurred If any copy error occurred returns a nil pointer O Spatial User Manual 57 O2Spatial C API Reference d_SpatialKey2D constructor Summary Syntax Arguments Returns Error Builds a zero surface 2 D spatial key from the corresponding point coordinates d_SpatialKey2D d_SpatialKey2D long x long y x y New spatial key coordinates None None 58 O Spatial User Manual Member functions descriptions d_SpatialKey2D constructor Summary Syntax Arguments Returns Error Builds a 2 D spatial key from the corresponding rectangle coordinates d SpatialKey2D d SpatialKey2D long xmin long ymin long xmax long ymax xmin y
6. d SpatialKey Object window distance geo_intersect coll Object window o2_bag geo_inside coll coll Object window o2_bag geo_close to d SpatialkKey Distance o2 bag O Spatial 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 4 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 lt d_Ref lt GeoEllipse gt gt bagResult int x Y cout lt lt Query point lt lt endl x enter number x 0 32767 enter number y 0 32767 d_ SpatialKey key x y query lt lt amp key d oql execute bagResult query Examples Get all the hotels at a distance less than 5 kilometres from Colorado Falls 36 O Spatial User Manual Querying Examples d Query query geo close to TheHotelsOfUSA 1 2 query lt lt ColoradoFalls gt get position query lt lt 5 Distance in kilometers Sea
7. nt isAPoint const void enlarge d_Distance distance onst d_SpatialKey amp operator const d SpatialKeye onst d_SpatialKey amp operator const d SpatialKeye the key coordinates const const const const const const 42 O Spatial User Manual Class definitions template lt class T gt class d GeoCollection public d_GeoCollection d_GeoCollection const char collection_name d_GeoCollection Handle hdCollection d_GeoCollection const d_GeoCollection lt T gt amp coll d_GeoCollection d_GeoCollection amp operator void insert_element const d Association lt d_SpatialKey void remove element const d Association lt d_SpatialKey void update element const d Association lt d SpatialKey const d _ Association lt d_SpatialKey void insert _ elements const d_ Array lt d Association lt d SpatialKey T gt gt amp pairs void remove elements const d_ Array lt d Association lt d SpatialKey T gt gt amp pairs d_Bag lt T gt d_Bag lt T gt d_Bag lt T gt d_Bag lt T gt contain const d_SpatialKey amp point intersect const d SpatialKeye window inside const d_SpatialKey amp window close to const d SpatialKeye window const d Distance distance const d_geoCollection lt T gt amp coll T gt amp T gt amp T gt amp T gt amp pair pair old_pair new_pair O Spatial User Manual
8. 43 O2Spatial C API Reference 4 2 Member functions descriptions This section gives the full description of the following C member functions for spatial index management For d_GeoCollection e close to e contain e d GeoCollection constructor e d GeoCollection constructor e insert_element e insert_elements e inside e intersect e operator e remove element e remove elements e update element For d_SpatialKey e clone e d SpatialKey2D constructor d_SpatialKey3D d_SpatialKey3D constructor e d SpatialKey2D constructor constructor e dimension e enlarge e getinternalKey e getSize e isAPoint e 02 get name e operator e operator 44 O Spatial User Manual Member functions descriptions close _ to Summary Syntax Arguments Returns Error 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 d_Bag lt T gt d_ GeoCollection lt T gt close to const d_SpatialKey amp window const d Distance distance window Window rectangle to be searched distance Distance added to the window which defines the search space Returns a bag containing the objects found Throws a d_Error object see the ODMG C Reference Guide if the following error occurs spatial key out of bounds d_Error InvalidSpatialKkey
9. O Spatial User Manual 45 O2Spatial C API Reference contain Summary Syntax Arguments Returns Error Gets the objects whose minimum rectangle contains the point d Bag lt T gt d_GeoCollection contain const d_SpatialKey amp point point Zero surface key to be tested Returns a bag containing the objects found None 46 O Spatial User Manual Member functions descriptions d_GeoCollection constructor Summary Syntax Arguments Returns Error Opens a collection indexed with a spatial index d_GeoCollection lt T gt d_GeoCollection Handle hdCollection hdCollection Handle to the collection to be opened None Throws a d_Error object see the ODMG C Reference Guide if one of the following errors occur 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 O Spatial User Manual 47 O2Spatial C API Reference d_GeoCollection constructor Summary Syntax Arguments Returns Error Opens a named collection indexed with a spatial index d_GeoCollection lt T gt d_GeoCollection const char CollectionName CollectionName Database name of the collection to be opened None Throws a d_Error object if one of the following errors occur
10. 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 O Spatial 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 Os 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 O Spatial User Manual Spatial index creation and deletion The creation 3 1 Spatial index creation and deletion The creation and de
11. with minimization of the traversal of the spatial index tree The parameter keyLength gives the length of a single key Thereis no definition of the key type in the OzEngine and OStore The spatial indexing module provides the structure of the key for the application when needed When using the standard O Spatial indexing engine keyArray is expected to be an array of pointers to SiBoundingBox objects and keyLength should be equal to zero This function fails if a scan operation is active on the spatial index 02_OK if successful error code otherwise O2E_NOTSUPPORTED The function is not implemented O2E_SIMALGO Error in Spatial Index Module algorithm O2E_ILLEGALCALL Function was called during a scan O2E PARAMETER The parameter idxDesc or keyArray or eltArray is incorrect O2E_NOSPACEONDISK No more space on disk o2x_spatial index insert _key o2x_spatial index delete key o2x_spatial index group delete key o2x_ spatial index replace key O Spatial User Manual 85 Spatial Indexing with O2Engine API 02x_spatial_index_delete_key Summary Syntax Description Returns Errors See Also Remove an entry from the spatial index include lt o2 h gt include lt o2_error h gt include lt o2_spatialindex h gt int o2x_spatial_index_delete_key o2x_ SpatialIndexDesc idxDesc int keyLength void key Handle element Removes the couple key element f
12. 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 O Spatial is a spatial indexing system capable of efficient storing and retrieval of geo referenced objects This system is based on a Rectangle Quadrant R Quad tree The spatial index is maintained by the O Spatial engine while the objects are maintained in an Os 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 e powerful query language that supports point window and proximity searches e fast maintenance when objects are added and deleted e efficient retrieval even for very large collections and very large query results Spatial representation When using the O Spatial 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 O Spatial API d_GeoCollection and d_Spatialkey O Spatial indexes and searches instances of d_SpatialKey which represent indexed object keys An application can use method
13. 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 Op system This document describes how to use spatial indexing including creating and deleting using the O Shell updating using C and querying using OQL and C The O spatial index module can also be used through a lower level programming interface Low level programming tools are provided by the O Spatial Index Engine API as well and described in Chapter 5 Spatial indexing with OoEngine API O Spatial User Manual 13 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 O Spatial enables application programmers to add spatial indexing and search capabilities to any collection of p
14. equivalent or not How to query spatially There are two ways of querying a spatial index e By calling a C method of the d_GeoCollection class e 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 O Spatial User Manual Querying Using OQL predicates d_Bag lt T gt d_Bag lt T gt d_Bag lt T gt d_Bag lt T gt contain intersect inside close_to const d SpatialKeye const d SpatialkKeye const d SpatialKeye const d SpatialKeye point window window 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 lt d Ref lt GeoEllipse gt gt bagResult int x Y cout lt lt Query point lt lt endl 0 32767 0 32767 x enter number x y enter number y bagResult Sindex contain d SpatialKey2D x 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 d SpatialKey
15. hd Moves the scan cursor forward if the parameter direction is set to 02X_NEXT or backward if direction is set to O2X_PREVIOUS and returns in the parameter hda handle to an indexed object pointed to by the scan cursor Any other value for the parameter direction is incorrect 02_OK if successful otherwise an error code notably O2E_KEYNOTFOUND which signifies that there are no more entries to recover O2E_NOTSUPPORTED The function is not implemented O2E_SIMALGO Error in Spatial Index Module algorithm O2E_PARAMETER The parameter idxScan or direction or hdis incorrect O2E_BADSCANID The parameter idxScan does not exist O2E_KEYNOTFOUND No more accessible entries o2x_spatial index scan _open o2x spatial index scan close 94 O Spatial User Manual INDEX O Spatial User Manual 95 INDEX axis 34 B Bounding box 15 31 C C 11 C Interface 11 class d GeoCollection 43 d SpatialKey 40 d SpatialKey2D 41 d SpatialKey3D 42 close to 31 close _ to 33 35 35 contain 30 contain 32 35 35 create spatial index options 23 create spatial index 23 D d_ Association 25 26 d Database set_default 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_SpatialKey
16. ieee remore MICE IIS ys esa itis update Ome os md en end Re a ln ni DAS LOS Ones Ch Spatial Rey 20 COS UMOR cnnic d SpatalKkey3D CONS MOI snn d _SpatialKkey3D COnSUCTOT Jesion A 0521101 E E E E EA EEE E A E A E T UE EE EEEE EEN E N inna DA asie dl E FA A nn nent PAO ch cdma E E A E O g2 gel DANE esan anu Re CE E E Ee Rew er Ea Cee E eevee er oe eee ee Spatial Indexing with O2Engine API 5 1 Introduction seiisssscssccssscscedssnntinnassondaanenpsooceasansaussaseunsestassaccanietuns 5 2 O2 Engine API Spatial Index INDEX O Spatial User Manual TABLE OF CONTENTS OoSpatial User Manual Introduction The O Spatial module provides spatial indexing and search capabilities for any collection of persistent objects in your Oo database This chapter presents an overview of the Os system an introduction to spatial indexing technology and a brief overview of O2Spatial To effectively use this manual you should have some knowledge of Os its C ODMG binding interface and of OQL O Spatial User Manual 9 1 Introduction 1 1 System overview The system architecture of Oo is illustrated in Figure 1 1 Development Tools External Interfaces O2 Dev Tools Dev Tools OQL c c OC Java MA O2Corba Database Engine O Spatial O Engine O Store ODB Access
17. lt o2_error h gt include lt o2_spatialindex h gt int o2x spatial index replace key o2x_SpatialIndexDesc idxDesc int keyLength void key Handle oldEltHd Handle newEltHd Substitutes the couple key oldE1tHd by the couple key newEltHd in the spatial index The spatial key is passed by the parameter key which provides the value and the parameter keyLength which provides the length The type of key is not defined at the level of the O2Engine and OoStore The spatial indexing module provides the structure of the key when needed at an application level When using the standard O gt Spatial indexing engine the key is expected to be a pointer to a SiBoundingBox object and keyLength should be equal to zero The parameters o1dEltHd and newEltHd are handles for O2 objects This function can execute if a scan operation is active on the spatial index 02_OK if successful error code otherwise O2E_NOTSUPPORTED The function is not implemented O2E_SIMALGO Error in Spatial Index Module algorithm O2E_PARAMETER The parameter idxDesc or key or oldEltHd or newEltHd is incorrect O2E_KEYNOTFOUND The couple key oldE1tHd does not exist in the index O2E_KEYALREADYEXISTS The couple key newEltHd already exists in the index 88 O Spatial User Manual O2 Engine API Spatial Index O2E_NOSPACEONDISK No more space on disk O Spatial User Manual 89 Spatial Indexing with O2Engin
18. of the NeXT Computer Inc Purify Quantify are registered trademarks of Rational Software Inc Search 97 is a registered trademark of Verity Inc Windows is a registered trademark of Microsoft Corporation All other company or product names quoted are trademarks or registered trademarks of their respective trademark holders Who should read this manual This manual presents the O 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 spatial index module provides both high level C and low level OoEngine API programming tools for spatial indexing This manual contains a comprehensive list of O Spatial methods and commands Other documents available are outlined click below See O2 Documentation set TABLE OF CONTENTS This manual is divided into the following chapters 1 Introduction 2 Setting up OSpatial 3 Using Oo2Spatial 4 O2Spatial C API reference 5 Spatial Indexing with OsEngine API O Spatial User Manual 2 TABLE OF CONTENTS Introduction 9 1 1 System CVE OW oriire asaan aa 10 1 2 O2 Efficient support for Geographical Info Systems 12 1 3 The O2Spatial MOUSE sstrnsussinnanasansatannetaniaienisinns 13 1 4 Object storage and retrieval
19. on a collection of versionned objects O2E_ERROR Internal error int create_spidx Handle o2_SiArgList SIOptions SIOptions SIOptions SIOptions SIOptions SIOptions SIOptions SIOptions SIOptions SIOptions SIOptions SIOptions indexOnlyContainsPoints return o2x spatial index create hdCollection 0 amp SIOptions o2_Boolean addArgument addArgument addArgument addArgument addArgument addArgument addArgument addArgument addArgument addArgument addArgument addArgument hdCollection SIOptions IndexType KeyCoordType Dimension D1_Min D2 Min D1_Max D2_Max D1_MinRegionSize D2_MinRegionSize MaxChildren Threshold OnlyPoints indexOnlyContainsPoints RQuadTree Integer32 2 0 0 40000 40000 2 2 4 167 void O Spatial User Manual 75 Spatial Indexing with O2Engine API 02x_spatial_indexed Summary Syntax Description Returns Errors Returns a handle to the spatial index associated with a collection of persistent objects include lt o2 h gt include lt o2_error h gt include lt o2_spatialindex h gt int o2x_spatial_indexed Handle colHd o2x_SpatialIndexDesc idxDesc Searches for the spatial index associated with a collection identified by colHd in the spatial index catalogue If the corresponding entry exists a han
20. pointer toa SiBoundingBox object which contains the requested rectangle A pointer to a SiEl lipse object which contains the requested ellipse 90 OoSpatial User Manual O2 Engine API Spatial Index Operation parameter Meaning areaValue parameter O2X_POLYGON Retrieve all the A pointer to a SiPoly objects which inter gon object which con sect agiven polygon tains thelist of the requested polygon verti O2X_POLYGON_ Retrieve all the STRICT objects which are ES inside a given poly gon O2X_POLYLINE Retrieve all the A pointer toa objects which inter SiPolyline object sect a given polyline which contains thelist of the requested polyline vertices Returns O02 _OK if successful error code otherwise Errors O2E_SIMALGO Error in Spatial Index Module algorithm O2E_PARAMETER The parameter idxDesc operation or areaValue is incorrect Samples SiBoundingBox requestedPoint x y x 1 y 1l if o2x_spatial_index_scan_open idxDesc int O2X CONTAIN sizeof SiBoundingBox amp requestedPoint amp idxScan 02_ OK return 1 Error O Spatial User Manual 91 Spatial Indexing with O2Engine API See Also Si3DPoint center x y SiEllipse requestedEllipse center xRadius yRadius if o2x_spatial_index_scan_open idxDesc int O2X ELLIPSE sizeof SiEllipse amp requestedEllipse amp idxScan 02_ OK return 1 Si3
21. 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_SpatialKey2D constructor 58 59 d SpatialKey2D 26 d_SpatialKey3D constructor 60 61 d_SpatialKey3D 26 Dd_MinRegionSize 30 74 delete spatial index 23 distance 34 F full text index FTI 14 O Spatial User Manual INDEX G getSpatialkKey 25 graphical coordinates 12 includefile 18 initialization of schema 18 inside 30 inside 33 35 35 intersect 30 intersect 32 35 35 Java 11 Library 18 O O2 Architecture 10 o2_set_GeoEllipse 27 OC 11 O2Corba 11 O2DBAccess 11 OzEngine 10 O2Graph 11 OoKit 11 O Look 11 O20DBC 11 O2Store 10 O Tools 11 OoWeb 11 Option Dd_Max 24 30 74 Dd Min 24 30 74 Dimension 24 30 74 IndexType 24 30 73 KeyCoordType 24 29 30 74 OnlyPoints 30 74 options create spatial index 23 options 23 OQL 11 R rectangle 34 R Quadtree 15 23 29 O Spatial User Manual 97 INDEX Spatial keys 12 SpatialIndexInfo 79 System Architecture 10 98 O Spatial User Manual
22. DPoint pointArray SiPolyline requestedPolyline numPoints pointArray if o2x_spatial_index_scan_open idxDesc int O2X POLYLINE sizeof SiPolyline amp requestedPolyline amp idxScan 02_ OK return 1 o2x_spatial_index_scan_close o2x_spatial_index_scan_read 92 O Spatial User Manual O2 Engine API Spatial Index o2x spatial index scan _ close Summary Syntax Description Returns Errors See Also Close a search operation on the spatial index include lt o2_error h gt include lt o2_spatialindex h gt int o2x_spatial_index_scan_close o2x_SpatialIndexScan idxScan Liberates the cursor of the scan idxScan 02_OK if successful error code otherwise O2E_SIMALGO Error in Spatial Index Module algorithm O2E_PARAMETER The parameter idxScan is incorrect O2E_BADSCANID The parameter idxScan does not exist o2x_ spatial index scan open o2x_ spatial index scan read O Spatial User Manual 93 Spatial Indexing with O2Engine API 02x_spatial_index_scan_read Summary Syntax Description Returns Errors See Also Return the next element of the spatial index which satisfies the operation of the current spatial scan include lt o2_error h gt include lt o2_spatialindex h gt int o2x_spatial_index_scan_read o2x_ SpatialIndexScan idxScan o2x ScanDirection direction Handle
23. Max KeyCoordType Maximum coordinate value for the KeyCoordType value given dimension d maximum value Other options are available for optimization of the spatial index see section 3 3 Spatial Index tuning 24 O Spatial 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 Os does not automatically manage the spatial index but it provides a programmative interface to populate the index Although in a future O 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 Op 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 thi
24. PI Reference intersect Summary Syntax Arguments Returns Error Gets the objects whose minimum rectangle has a non empty intersection with the rectangle window d Bag lt T gt d_GeoCollection lt T gt intersect const d_SpatialKey amp window window Window space to be searched Returns a bag containing the objects found None 52 O Spatial User Manual Member functions descriptions operator Summary Assigns a d GeoCollection object to another Syntax d_GeoCollection amp d_GeoCollection lt T gt operator const d_GeoCollection coll Arguments Collection to be opened Returns None Error None O Spatial User Manual 53 O2Spatial C API Reference remove element Summary Syntax Arguments Returns Error Removes an element from the spatial index void d GeoCollection lt T gt remove elements const d Association lt d_SpatialKey T gt amp pair pair Pair to be removed from the spatial index None None 54 O Spatial User Manual Member functions descriptions remove elements Summary Syntax Arguments Returns Error Removes several elements from the spatial index void d GeoCollection lt T gt remove elements const d Array lt d_ Association lt d_SpatialKey T gt gt amp pair pair Array pairs to be removed from the spatial index None None O Spatial User Manual 55
25. de query returns the ellipse and pentagon but neither the triangle nor the trapezoid since they project beyond the window limits e Retrieve all the objects which are within a given distance of a point close_to MyGeoObjects SpatialKey2D x y dist dist For this figure the close_to query returns the triangle trapezoid and pentagon 33 O Spatial User Manual 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 O 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 nota 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
26. dex tree in the volume declared by the parameter volumeName or in the same volume of the collection if volumeName is set to zero Initializes the spatial index as a function of the parameter opaque When using the O2 Spatial indexing engine the parameter opaque is expected to be of type o2_SiArgList This class enables the user to set all the spatial index parameters as option value couples The following example shows how to build such an object o2_SiArgList argList argList addArgument IndexType RQuadTree argList addArgument KeyCoordType Integer32 argList addArgument Dimension 2 The arguments which must be set by using an o2_ SiArgList object include those described in section 3 5 The arguments are described below O Spatial User Manual 73 Spatial Indexing with O2Engine API Option Type Description Recom mended value IndexType string Name of the spatial index algorithm RQuadTree Must be RQuadTree to use the O Spatial indexing algorithm Dimension integer Number of coordinates of the indexed 2 space OnlyPoints boolean True if indexed objects are always points False KeyCoordType string Type used for spatial key coordinates Integer32 Must be Integer16 or Integer32 Dd_Min KeyCoordType Minimum coordinate value for the given KeyCoordType value dimension d used for internal coordi minimum value nates scaling optimization Dd_Max KeyCoordTy
27. dimension d used for internal coordi nates scaling optimization Minimum size of an indexed region in KeyCoordType based coordinates for dimension d Such a region will not be segmented more Default value RQuadTree False Integer32 KeyCoordType minimum value KeyCoordType maximum value 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 bound aries 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 O Spatial User Manual Querying O2 Spatial keys e 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 O Spatial keys The geographical position of each object is stored in the index The key type used by the O spatial indexing m
28. dle for the spatial index is created and its value is assigned to the parameter idxDesc Otherwise the value NULL is assigned to the parameter idxDesc The spatial index descriptor created by the 02x_spatial_indexed function should always be deleted using the o2x_spatial_index_free_descriptor function 02_OK if successful error code otherwise O2E_PARAMETER The parameter colHd or idxDesc is incorrect O2E_NOTINDEXED There is no spatial index for this collection O2E_INVALID COLLECTION The handle colHd is invalid or is not a handle to a persistent collection 76 OoSpatial User Manual O2 Engine API Spatial Index 02x_spatial_index_delete Summary Syntax Description Returns Errors Remove a spatial index associated with a collection of persistent objects include lt o2_error h gt include lt o2_spatialindex h gt int o2x_spatial_index_delete o2x_SpatialIndexDesc idxDesc Deletes the spatial index identified by the parameter idxDesc and removes the corresponding entry in the spatial index catalogue The operation is not executed if there exists a scan operation running at the time of the call 02_OK if successful error code otherwise O2E_SIMALGO Error in Spatial Index Module algorithm O2E_PARAMETER The parameter idxDesc is incorrect O2E_ILLEGALCALL Function was called during a scan O Spatial User Manual 77 Spatial Indexing with O2Engine API
29. e API 02x_spatial_index_scan_open Summary Syntax Description Start a search operation on the spatial index include lt o2_error h gt include lt o2_spatialindex h gt int o2x_spatial_index_scan_open o2x_ SpatialIndexDesc idxDesc int operation int areaLength void areaValue o2x_SpatialIndexScan idxScan Initializes a scan on the spatial index identified by idxDesc and returns an external identifier for it as the variable idxScan The parameters operation areaLength and areaValue define the spatial predicate which is applied to filter the entries returned by the function 0o2x_spatial_index_scan_read The available spatial operations are defined by a code at the application level This code is transferred by the parameter operation When using the O2Spatial indexing engine the possible values for the parameters operation and areaValue are as follows Operation parameter Meaning areaValue parameter O2X_ CONTAIN O2X_INTERSECT O2X_IS CONTAINED O2X_ELLIPSE O2X_ELLIPSE_ STRICT Retrieve all the objects which con tain a given point Retrieve all the objects which inter sect a given rectan gle Retrieve all the objects which are inside a given rect angle Retrieve all the objects which inter sect a given ellipse Retrieve all the objects which are inside a given ellipse A pointer toa SiBoundingBox object which contains the requested point A
30. e otherwise O2E_PARAMETER The spatial index descriptor idxDescis incorrect O Spatial User Manual 81 Spatial Indexing with O2Engine API 02x_spatial_index_get_collection Summary Syntax Description Returns Return the handle of the indexed collection include lt o2 h gt include lt o2_error h gt include lt o2_spatialindex h gt Handle o2x_spatial_index_get_collection o2x_SpatialIndexDesc idxDesc Return the handle of the collection of persistent objects associated with the spatial index identified by idxDesc A valid collection handle if successful a NULL handle otherwise 82 O Spatial User Manual O2 Engine API Spatial Index 02x_spatial_index_insert_key Summary Syntax Description Returns Errors Insert a new entry in the spatial index include lt o2 h gt include lt o2_error h gt include lt o2_spatialindex h gt int o2x_spatial_index_insert_key o2x_ SpatialIndexDesc idxDesc int keyLength void key Handle element Inserts an entry key element into the spatial index The spatial key is passed by the parameter key which provides the value and the parameter keyLength which provides the length The type of key is not defined at the level of the Os2Engine and OoStore The spatial indexing module provides the structure of the key when needed at the level of the application When using the standard O2Spatial indexing en
31. ersistent objects When an error is detected O Spatial 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 O Spatial API The following classes are included e d SpatialKey d_SpatialKey2D d_SpatialKey3D e d GeoCollection O Spatial 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 amp 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 amp operator const d SpatialKeye Key union operator virtual const d_SpatialKey amp operator const d_SpatialKey amp 40 O Spatial User Manual Class definitions class d_Spat
32. ersistent objects stored in an O database An O application using O Spatial can perform three functions e Index collections of persistent geo referenced objects to make them efficiently searchable e Search and retrieve objects that satisfy users queries e Maintain and optimize spatial indexes O Spatial applications can use the following search techniques e Searching for objects that intersect with a particular spatial point e Searching for objects that intersect with a certain window e Searching for objects that are inside a certain window e Searching for objects that are within a certain distance from a particular spa tial point An application program interface API enables you to integrate spatial index capabilities within your Op 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 O Spatial 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
33. gine the key is expected to be a pointer to a SiBoundingBox object and keyLength should be equal to zero The parameter element is a handle of the O2 object to be indexed This function fails if a scan operation is active on the spatial index 02_OK if successful error code otherwise O2E_NOTSUPPORTED The function is not implemented O2E_SIMALGO Error in Spatial Index Module algorithm O2E_ILLEGALCALL Function was called during a scan O2E_PARAMETER The parameter idxDesc or key or element is incorrect O2E_KEYALREADYEXISTS The couple key element already exists in the index O2E_NOSPACEONDISK No more space on disk O Spatial User Manual 83 5 Spatial Indexing with O2Engine API See Also o2x_spatial_index_group_insert_key o2x_spatial_index_delete_key o2x_spatial_index_group_delete_key o2x_spatial_index_replace_key 84 O Spatial User Manual O2 Engine API Spatial Index o2x spatial index_ group _insert_key Summary Syntax Description Returns Errors See Also Insert multiple new entries in the spatial index include lt o2 h gt include lt o2_error h gt include lt o2_spatialindex h gt int o2x spatial index group insert _key o2x_SpatialIndexDesc idxDesc int card int keyLength void keyArray Handle eltArray Inserts multiple entries key i eltArray i with i varying between 0 card 1 into the spatial index
34. h 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 O Spatial User Manual 23 3 Using O2Spatial e 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 com mand This configuration file specifies a value for each option you want to cus tomize 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 e Or using a low level interface described in Chapter 5 Spatial Indexing with O2Engine API The following options can be specified for the Oo spatial index the configuration file is not case sensitive Option Type Description Default value IndexType string Name of the spatial index algorithm RQuadTree Must be RQuadTree to use the O Spatial indexing algorithm Dimension integer Number of dimensions in the indexed 2 space KeyCoordType string Type used for spatial key coordinates Integer32 either Integer16 or 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 KeyCoord Minimum coordinate value for the KeyCoordType Type value given dimension d minimum value Dd_
35. ialKey2D 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 amp 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 amp operator const d SpatialKeye virtual const d_SpatialKey amp operatort const d SpatialKeye Return long xmin long xmax long ymin long ymax the key coordinates const const const const O Spatial User Manual 41 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 amp key virtual d_SpatialKey3D virtual d_SpatialKey clone const Return 3 virtual i virtual c virtual c virtual i virtual i virtual virtual c virtual c Return long long long long long long xmin xmax ymin ymax zmin zmax nt dimension const onst char o2 get name const onst void getInternalKey const nt getSize const
36. ing 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 Op Makegen User Manual which describe how to write and build a C application with Oo When using the standard O Spatial indexing engine with the spatial index interface of the Op Engine API you also need the following include files o2_SiArgList hxx SiEllipse hxx SiBoundingBox hxx SiPolygon hxx Si3DPoint hxx SiPolyline hxx 18 O Spatial User Manual Schema initialization Schema initialization If you want to use spatial operators embedded in OQL queries you must initialize the Op 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 A D O Spatial User Manual 19 Setting Up O2Spatial 20 O Spatial User Manual Using O gt Spatial This chapter presents an example of a simple OoSpatial application The example introduces the main components of the OoSpatial architecture and shows how the O Spatial API can be used to build O applications that make use of spatial indexing SI
37. letion commands An O spatial index is created and deleted through the O database administration shell like any other O index see the Op System Administration Guide The OoDBA shell commands are the following create spatial index lt collection name gt options options file name delete spatial index lt collection name gt 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 anamed 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 lt d_Ref lt GeoEllipse gt gt have been previously imported see C Binding Guide constant name TheEllipses o2_set_GeoEllipse create spatial index TheEllipses Spatial index options The O spatial index module uses a generic indexing algorithm based on R Quadtrees Each Oo spatial index is initialized with default parameter values whic
38. min xmax ymax New spatial key coordinates None None O Spatial User Manual 59 O2Spatial C API Reference d_SpatialKey3D constructor Summary Syntax Arguments Returns Error Builds a zero surface 3 D spatial key from the corresponding point coordinates d_SpatialKey3D d_SpatialKey3D long x long y long z X yY Z New spatial key coordinates None None 60 O Spatial 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 New spatial key coordinates Returns None Error None O Spatial User Manual 61 O2Spatial C API Reference dimension Summary Syntax Arguments Returns Error Gets the indexed space dimension two if two coordinates are required to describe a point three if three coordinates are needed and so on virtual int d_SpatialKey dimension const None Returns the dimension as an integer None 62 O Spatial User Manual Member functions descriptions enlarge Summary Syntax Arguments Returns Distance p Resizes the spatial key void d SpatialKey enlarge d Distance distance The distance Returns an enlarged ke
39. ns the number of leaf nodes in the spatial index tree If mask amp O2X_SI_EMPTYLEAFCNT is TRUE emptyLeafCount contains the number of empty leaf nodes in the spatial index tree If mask amp O2X_SI_LEAFMFF is TRUE leafMeanFillFactor contains the percentage of occupied leaf nodes in the spatial index tree The percentage of occupied leaves is distinguished from the percentage of occupied intermediary nodes in that leaves and nodes can contain different maximum numbers of keys Moreover the notion of an empty leaf may not be significant for certain spatial index algorithms 02_ OK if successful error code otherwise O2E_NOTSUPPORTED The function is not implemented O2E_SIMALGO Error in Spatial Index Module algorithm O2E_ILLEGALOP The parameter idxDesc or idxInfo is incorrect O Spatial User Manual O2 Engine API Spatial Index 02x_spatial_index_free_descriptor Summary Syntax Description Returns Errors Free the memory used by a spatial index descriptor include lt o2_error h gt include lt o2_spatialindex h gt int o2x_spatial_index_free_descriptor o2x_SpatialIndexDesc idxDesc Free the memory associated with the spatial index descriptor created by o2x_spatial_indexed Every spatial index descriptor should be freed by o2x_ spatial index free descriptor After a call to o2x spatial index free descriptor a spatial descriptor is always NULL 02_OK if successful error cod
40. nsion int depth int entryCount int allNodeCount int nodeCount double nodeMeanFillFactor int leafCount int emptyLeafCount double leafMeanFillFactor o2x SpatialIndexInfo The values which can be used to set the bit mask mask are 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 e If mask amp O2X_SI_DIMENSION is TRUE dimension contains the dimen sion of the spatial index e f mask amp O2X_SI_DEPTH is TRUE depth contains the depth of the spa tial index tree O Spatial User Manual 79 Spatial Indexing with O2Engine API Returns Errors If mask amp O2X_SI_ENTRYCNT is TRUE entryCount contains the number of entries key element in the spatial index tree Note that the number of spatial index entries may be greater than the number of objects really inserted in the index since some objects may belong to several quad rants If mask amp O2X _SI_ALLNODECNT is TRUE allNodeCount contains the total number of nodes in the spatial index tree If mask amp O2X_SI_NODECNT is TRUE nodeCount contains the number of intermediary nodes in the spatial index tree including the root node If mask amp O2X_SI_NODEMFF is TRUE nodeMeanFillFactor contains the percentage of occupied intermediary nodes in the spatial index tree If mask amp O2X_SI_LEAFCNT is TRUE leafCount contai
41. odule is the minimum rectangle containing the indexed geographical objects called the bounding box The bounding box principle is illustrated in the figure below 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 O Spatial User Manual 31 3 Using O2Spatial e 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 For this figure the contain query returns the triangle and ellipse e 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 spe cific window for example intersect MyGeoObjects SpatialKey2D xmin ymin xmax ymax xmin xmax For this figure the intersect query returns the triangle ellipse and trapezoid e Retrieve all the objects which are inside a specific window 32 O Spatial User Manual Querying Spatial query examples inside MyGeoObjects SpatialKey2D xmin ymin xmax ymax xmax For this figure the insi
42. patialIndexDesc idxDesc int card int keyLength void key Handle eltArray Removes multiple entries key i eltArray i with i varying between 0 card 1 from the spatial index with minimization of the traversal of the spatial index tree The parameter keyLength gives the length of a single key Thereis no definition of the key type in the OzEngine and OStore The spatial indexing module provides the structure of the key for the application when needed When using the standard O Spatial indexing engine keyArray is expected to be an array of pointers to SiBoundingBox objects and keyLength should be equal to zero This function fails if a scan operation is active on the spatial index 02_OK if successful error code otherwise O2E_NOTSUPPORTED The function is not implemented O2E_SIMALGO Error in Spatial Index Module algorithm O2E_ILLEGALCALL Function was called during a scan O2E PARAMETER The parameter idxDesc or keyArray or eltArray is incorrect O2E_NOSPACEONDISK No more space on disk o2x_spatial index insert _key o2x_ spatial index group insert _key o2x_spatial index delete key o2x_ spatial index replace key O Spatial User Manual 87 Spatial Indexing with O2Engine API 02x_spatial_index_replace_key Summary Syntax Description Returns Errors Substitute one entry with another entry in the spatial index include lt o2 h gt include
43. pe Maximum coordinate value for the given KeyCoordType value dimension d used for internal coordi maximum value nates scaling optimization Dd_Min integer Minimum size of an indexed region in 2 RegionSize KeyCoordType based coordinates for dimension d Such a region will not be segmented more MaxChildren integer Maximum number of subspaces gener 2Dimension ated each time a given indexed space needs to be segmented used when a R QuadTree node is saturated Threshold integer Number of key values couples in each Highest possi R QuadTree node Must be greater or ble value see equal to 2 and less or equal than description 167 if KeyCoordType integer 32 Dimension 2 126 if KeyCoordType Integer 32 Dimension 3 At this level of programming no default value is provided for these parameters An appropriate value must then be set up for all of them Returns 02_OK if successful error code otherwise Errors O2E_NOTSUPPORTED The function is not implemented O2E_SIMALGO Error in Spatial Index Module algorithm O Spatial User Manual O2 Engine API Spatial Index Sample O2E_ PARAMETER The parameter opaque is incorrect O2E_INVALIDCOLLECTION The handle colHd is invalid or is not a handle toa persistent collection O2E_IS_INDEXED There is no spatial index for this collection O2E_NOSPACEONDISK No more space on disk O2E_PERMISSIONDENIED The handle colHd is valid but no spatial index can be created
44. r 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 Op page size KeyCoord Type 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 O Spatial User Manual 29 Using O2Spatial The full list of the O spatial index tuning options are the following Option IndexType Dimension OnlyPoints KeyCoordType Dd_Min Dd_Max Dd_Min RegionSize Type string integer boolean string KeyCoordType value KeyCoordType value integer 3 6 Querying Description Name of the spatial index algorithm Must be RQuadTree to use the O Spatial indexing algorithm Number of coordinates of the indexed space True if indexed objects are always points Type used for spatial key coordinates Must be Integer16 or Integer32 Minimum coordinate value for the given dimension d used for internal coordi nates scaling optimization Maximum coordinate value for the given
45. rator Summary Syntax Arguments Returns Error Assigns a key to another d SpatialKeye d_SpatialKey operator const d_SpatialKey amp key const The key to be assigned None None 68 O Spatial User Manual Member functions descriptions operator Summary Enlarges a key with the area covered by another key Syntax virtual const d_SpatialKey amp d_SpatialKey operator const d_SpatialKey amp const Arguments The key to be included Returns Returns an enlarged key as shown in the following 2 D drawing ee Wy re iow ws Key to be included New key Old key Error None O Spatial User Manual 69 O2Spatial C API Reference 70 OoSpatial User Manual 5 Spatial Indexing with O Engine API This chapter describes the use of spatial indexing with the O2Engine API It contains the following sections e Introduction e O2 Engine API Spatial Index O Spatial User Manual 71 Spatial Indexing with O2Engine API 5 1 5 2 Introduction The OzEngine API Spatial Index interface is made up of a set of functions that allow you to maintain and access a spatial index of an O2 database The library of spatial index functions allows to create remove update and query the spatial index associated with a collection of O2 objects O Engine API Spatial Index The spa
46. rch 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 lt lt amp 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 02 bag Forest geo_intersect SequoiaForests 1 where forest surface gt 2 The two parameters are query lt lt YellowstonePark gt getSpatialKey a bag of forests query lt lt 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 O Spatial User Manual 37 Using O2Spatial If you want to use both indexes 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 gt 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 O Spatial User Manual O Spatial C 4 API Reference The O Spatial C API enables users to use O Spatial indexing and searching facilities for a collection of p
47. rk O Spatial User Manual 11 Introduction 1 2 O 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 Oz 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 c
48. rom the spatial index The spatial key is passed by the parameter key which provides the value and the parameter keyLength which provides the length The type of key is not defined at the level of the O2Engine and OStore The spatial indexing module provides the structure of the key when needed at an application level When using the standard Oo2Spatial indexing engine the key is expected to be a pointer to a SiBoundingBox object and keyLength should be equal to zero The parameter element is a handle for the O2 indexed object This function fails if a scan operation is active on the spatial index 02_ OK if successful error code otherwise O2E_NOTSUPPORTED The function is not implemented O2E_SIMALGO Error in Spatial Index Module algorithm O2E_ILLEGALCALL Function was called during a scan O2E_PARAMETER The parameter idxDesc or key or element is incorrect O2E_KEYNOTFOUND The couple key element already exists in the index o2x_spatial_index_insert_key o2x_spatial_index_group_insert_key o2x_spatial_index_delete_key o2x_spatial_index_replace_key 86 O Spatial User Manual O2 Engine API Spatial Index 02x_spatial_index_group_delete_key Summary Syntax Description Returns Errors See Also Remove multiple entries from the spatial index include lt o2 h gt include lt o2_error h gt include lt o2_spatialindex h gt int o2x_spatial_index_goupr_delete_key o2x_S
49. ross 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 Op 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 O Spatial User Manual The O2Spatial module 1 3 The O Spatial module This document presents the Op spatial indexing module This module enables you to develop efficient applications managing geographical information utilizing spatial indexing The module uses the Op ODMG C binding and the OQL query language The spatial indexing module
50. s 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 4_ Error UnknownIndex 48 O Spatial User Manual Member functions descriptions insert_element Summary Syntax Arguments Returns Error Inserts an element into the spatial index void d GeoCollection lt T gt insert elements const d Association lt d_SpatialKey T gt amp pair pair Pair to be inserted within the spatial index None None O Spatial User Manual 49 O2Spatial C API Reference insert_elements Summary Syntax Arguments Returns Error Inserts several elements into the spatial index void d GeoCollection lt T gt insert elements const d Array lt d_ Association lt d_SpatialKey T gt gt amp pair pair Array pairs to be inserted within the spatial index None None 50 O Spatial User Manual Member functions descriptions inside Summary Syntax Arguments Returns Error Gets the objects whose minimum rectangle is strictly included in the rectangle window d Bag lt T gt d GeoCollection lt T gt inside const d_SpatialKey amp window window Window space to be searched Returns a bag containing the objects found None O Spatial User Manual 51 O2Spatial C A
51. s 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 O Spatial User Manual 15 Introduction 16 O Spatial User Manual Setting Up O Spatial Various O Spatial related files are needed to use the Spatial index This chapter presents how to set up your Oo system in order to use O Spatial This chapter presents how to set up your O system to use Op Spatial The chapter is composed of the following sections O2HOME Files e Schema initialization O Spatial User Manual 17 2 Setting Up O2Spatial O2HOME Files When you purchase Os O Spatial is available upon request After installing Oo you can find the following O Spatial related files in your Op home directory These files are needed to build an O Spatial application Include File o2spatial CC hxx file you must include to use the O Spatial C interface o2_spatialindex h file which must be included to use the spatial index interface of the O Engine API o2_spatial oql file you need to initialize O schemas where spatial queries will be performed through OQL Libraries libo2si so O Spatial interface libo2si_engine so standard O Spatial indexing engine You must add both libraries at link time when build
52. s standard class the O system uses the ODMG d_Association structure to associate a key and its value O Spatial User Manual 25 3 Using O2Spatial template lt class K class V gt class d _ Association public K key V value d_Association d_Association const K amp K const Ve V The spatial index module introduces the d_GeoCollection which is the C interface for accessing the O 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 d_SpatialKey3D 26 O Spatial 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 lt d Ref lt GeoEllipse gt gt 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 e
53. t center_x center_y int radius_x radius_y cout lt lt Center lt lt endl center_x enter_number x 32767 center _y enter_number y 32767 cout lt lt Radius lt lt endl radius_x enter_number x 32767 radius_ y enter number y 32767 pair value new database GeoEllipse center _ x center_y radius x radius y pair key pair value gt getSpatialKey Insert the new object into the bag and the geo collection Sindex insert element pair Ellipses insert element pair value transaction validate O Spatial User Manual Spatial Index tuning Update method Update method If a spatialKey Object association is modified you must update the O system by calling the following method void d_GeoCollection lt T gt update_element const d_Association lt d_SpatialKey T gt amp old pair const d_Association lt d_SpatialKey T gt amp 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 O spatial index options Op spatial indexes are maintained as R QuadTrees Several options enable these trees to be adapted and optimized to the user needs fo
54. tial index interface of the O2Engine API defines a collection of operations available to the developer of O2Engine applications for managing a spatial index The commands are divided into three categories of operations 1 The operations on the spatial index e o2x_spatial_index_create e o2x_spatial_indexed e o2x_spatial_index_delete e o2x_spatial_index_reorganize e o2x_spatial_index_get_info e o2x_spatial_index free descriptor e o2x spatial _ index get collection 2 The operations on the elements of the spatial index e o2x_ spatial index insert _ key e o2x spatial index group insert key e o2x_ spatial index delete key e o2x_ spatial index group delete key e o2x spatial index replace key 3 The search operations on the spatial index e o2x_spatial_index_scan_open e o2x_spatial_index_scan_close e o2x_spatial_index_scan_read 72 O Spatial User Manual O2 Engine API Spatial Index 02x_spatial_index_create Summary Syntax Description Create a spatial index associated with a collection of persistent objects include lt o2 h gt include lt o2_error h gt include lt o2_spatialindex h gt int o2x_spatial_index_create Handle colHd char volumeName void opaque Verifies in the spatial index catalogue that the collection indicated by the parameter colHd has not been previously associated with a spatial index Creates the Oo Store file for the spatial in
55. ures available with Oo persistence collection management transaction management OQL queries etc C e C e Java e O2C e OQL Ox functions can be invoked by C programs ODMG compliant C binding ODMG compliant Java binding A powerful and elegant object oriented fourth generation language specialized for easy development of object database applications ODMG standard easy to use SQL like object query language with special features for dealing with complex Oo objects and methods Op Development Tools e O gt Graph e O2Look e Ookit e OosTools Create modify and edit any type of object graph Design and develop graphical user interfaces provides interactive manipulation of complex and multimedia objects Library of predefined classes and methods for faster development of user applications Complete graphical programming environment to design and develop O database applications Standard Development Tools All standard programming languages can be used with standard environments e g Visual C Sun Sparcworks External Interfaces e OoCorba e O2DBAccess e O20DBC e OoWeb Create an Oo Orbix server to access an Oo database with CORBA Connect O2 applications to relational databases on remote hosts and invoke SQL statements Connect remote ODBC client applications to Oo databases Create an Oo World Wide Web server to access an Oo database through the internet netwo
56. xample 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 lt T gt insert element const d_ Association lt d SpatialKey T gt amp pair void d GeoCollection lt T gt remove element const d_ Association lt d SpatialKey T gt amp 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 O Spatial User Manual 27 3 Using O2Spatial void d GeoCollection lt T gt insert elements const d_ Array lt d Association lt d SpatialKey T gt gt amp pairs void d GeoCollection lt T gt remove elements const d_ Array lt d Association lt d SpatialKey T gt gt amp pairs The following example shows how a geo referenced object can be added to the index d_Set lt d_Ref lt GeoEllipse gt gt Ellipses TheEllipses d_GeoCollection lt d_Ref lt GeoEllipse gt gt Sindex TheEllipses d_Association lt d_SpatialKey d_Ref lt GeoEllipse gt gt pair d_Transaction transaction transaction begin Set parameters for a new ellipse object in
57. y as shown in the following 2 D drawing Error Old key area New key area L Lg Distance None O Spatial User Manual 63 O2Spatial C API Reference getinternalKey Summary Syntax Arguments Returns Error Gets the internal spatial key structure const void d_SpatialKey getInternalKey const None Returns a pointer to the internal spatial key structure None 64 O Spatial User Manual Member functions descriptions getSize Summary Syntax Arguments Returns Error Gets the internal spatial key structure size int d_SpatialKey getSize const None Returns the size in bytes None O Spatial User Manual 65 O2Spatial C API Reference isAPoint Summary Syntax Arguments Returns Error Checks whether the spatial key is a point int d_SpatialKey isAPoint const None Returns TRUE if the spatial key is a zero surface rectangle and FALSE otherwise None 66 O Spatial User Manual Member functions descriptions o2_ get name Summary Gets the key class name used by O for its own type verification Syntax const char d SpatialKey 02 get_ name const Arguments None Returns Returns a string which contains the key class name Error None O Spatial User Manual O2Spatial C API Reference ope

Download Pdf Manuals

Related Search

Related Contents

2.17217_PMSInstallGu.. - Microenterprise Access to Banking  User Manual a product Pay close attention to the guarantee  DNS-320 User Manual  Orion-M - Future Design Controls  仕 様      続きはこちら    GV-LPR License Plate Recognition User Manual  

Copyright © All rights reserved. Failed to retrieve file