[ceph.git] / ceph / src / boost / libs / geometry / doc / index / rtree / quickstart.qbk

[/============================================================================
  Boost.Geometry Index

  Copyright (c) 2011-2012 Adam Wulkiewicz.

  Use, modification and distribution is subject to the Boost Software License,
  Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
  http://www.boost.org/LICENSE_1_0.txt)
=============================================================================/]

[section:rtree_quickstart Quick Start]

This Quick Start section shows simple way to creating a typical R-tree and perform
spatial query.

The code below assumes that following files are included and namespaces used.

[rtree_quickstart_include]

Typically you'll store e.g. `std::pair<Box, MyGeometryId>` in the __rtree__. `MyGeometryId`
will be some identifier of a complex `Geometry` stored in other container, e.g. index type
of a `Polygon` stored in the vector or an iterator of list of `Ring`s. To keep it simple to
define `Value` we will use predefined __box__ and unsigned int.

[rtree_quickstart_valuetype]

R-tree may be created using various algorithm and parameters. You should choose the algorithm you'll
find the best for your purpose. In this example we will use quadratic algorithm. Parameters are
passed as template parameters. Maximum number of elements in nodes is set to 16. 

[rtree_quickstart_create]

Typically `Value`s will be generated in a loop from e.g. `Polygon`s stored in some other container.
In this case `Box` objects will probably be created with `geometry::envelope()` function.
But to keep it simple lets just generate some boxes manually and insert them into the R-tree by
using `insert()` method.

[rtree_quickstart_insert]

There are various types of spatial queries that may be performed, they can be even combined together
in one call. For simplicity, we use the default one. The following query return values intersecting
a box. The sequence of `Values` in the result is not specified.

[rtree_quickstart_spatial_query]

Other type of query is k-nearest neighbor search. It returns some number of values nearest to some point
in space. The default knn query may be performed as follows. The sequence of `Values` in the result is not specified.

[rtree_quickstart_nearest_query]

At the end we'll print results.

[rtree_quickstart_output]

[h3 More]
More information about the R-tree implementation, other algorithms and queries may be found in
other parts of this documentation.

[endsect]
Commit	Line	Data
7c673cae FG	1	[/============================================================================
	2	Boost.Geometry Index
	3
	4	Copyright (c) 2011-2012 Adam Wulkiewicz.
	5
	6	Use, modification and distribution is subject to the Boost Software License,
	7	Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
	8	http://www.boost.org/LICENSE_1_0.txt)
	9	=============================================================================/]
	10
	11	[section:rtree_quickstart Quick Start]
	12
	13	This Quick Start section shows simple way to creating a typical R-tree and perform
	14	spatial query.
	15
	16	The code below assumes that following files are included and namespaces used.
	17
	18	[rtree_quickstart_include]
	19
	20	Typically you'll store e.g. `std::pair<Box, MyGeometryId>` in the __rtree__. `MyGeometryId`
	21	will be some identifier of a complex `Geometry` stored in other container, e.g. index type
	22	of a `Polygon` stored in the vector or an iterator of list of `Ring`s. To keep it simple to
	23	define `Value` we will use predefined __box__ and unsigned int.
	24
	25	[rtree_quickstart_valuetype]
	26
	27	R-tree may be created using various algorithm and parameters. You should choose the algorithm you'll
	28	find the best for your purpose. In this example we will use quadratic algorithm. Parameters are
	29	passed as template parameters. Maximum number of elements in nodes is set to 16.
	30
	31	[rtree_quickstart_create]
	32
	33	Typically `Value`s will be generated in a loop from e.g. `Polygon`s stored in some other container.
	34	In this case `Box` objects will probably be created with `geometry::envelope()` function.
	35	But to keep it simple lets just generate some boxes manually and insert them into the R-tree by
	36	using `insert()` method.
	37
	38	[rtree_quickstart_insert]
	39
	40	There are various types of spatial queries that may be performed, they can be even combined together
	41	in one call. For simplicity, we use the default one. The following query return values intersecting
	42	a box. The sequence of `Values` in the result is not specified.
	43
	44	[rtree_quickstart_spatial_query]
	45
	46	Other type of query is k-nearest neighbor search. It returns some number of values nearest to some point
	47	in space. The default knn query may be performed as follows. The sequence of `Values` in the result is not specified.
	48
	49	[rtree_quickstart_nearest_query]
	50
	51	At the end we'll print results.
	52
	53	[rtree_quickstart_output]
	54
	55	[h3 More]
	56	More information about the R-tree implementation, other algorithms and queries may be found in
	57	other parts of this documentation.
	58
	59	[endsect]