GRASS GIS 8 Programmer's Manual  8.4.0dev(2024)-f8115df121
rtree.h File Reference
#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include <sys/types.h>
#include <grass/config.h>
Include dependency graph for rtree.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  RTree_Rect
 
union  RTree_Child
 
struct  RTree_Branch
 
struct  RTree_Node
 
struct  nstack
 
struct  NodeBuffer
 
struct  RTree_PartitionVars
 
struct  RTree
 
struct  RTree::_recycle
 

Macros

#define TRUE   1
 
#define FALSE   0
 
#define MAXCARD   9
 
#define NODECARD   MAXCARD
 
#define LEAFCARD   MAXCARD
 
#define MAXLEVEL   20 /* 8^MAXLEVEL items are guaranteed to fit into the tree */
 
#define NODE_BUFFER_SIZE   32
 

Typedefs

typedef double RectReal
 
typedef int SearchHitCallback(int id, const struct RTree_Rect *rect, void *arg)
 
typedef int rt_search_fn(struct RTree *, struct RTree_Rect *, SearchHitCallback *, void *)
 
typedef int rt_insert_fn(struct RTree_Rect *, union RTree_Child, int, struct RTree *)
 
typedef int rt_delete_fn(struct RTree_Rect *, union RTree_Child, struct RTree *)
 
typedef int rt_valid_child_fn(union RTree_Child *)
 

Functions

int RTreeSearch (struct RTree *, struct RTree_Rect *, SearchHitCallback *, void *)
 Search an R*-Tree. More...
 
int RTreeInsertRect (struct RTree_Rect *, int, struct RTree *)
 Insert an item into a R*-Tree. More...
 
void RTreeSetRect1D (struct RTree_Rect *r, struct RTree *t, double x_min, double x_max)
 Set one dimensional coordinates of a rectangle for a given tree. More...
 
void RTreeSetRect2D (struct RTree_Rect *r, struct RTree *t, double x_min, double x_max, double y_min, double y_max)
 Set two dimensional coordinates of a rectangle for a given tree. More...
 
void RTreeSetRect3D (struct RTree_Rect *r, struct RTree *t, double x_min, double x_max, double y_min, double y_max, double z_min, double z_max)
 Set three dimensional coordinates of a rectangle for a given tree. More...
 
void RTreeSetRect4D (struct RTree_Rect *r, struct RTree *t, double x_min, double x_max, double y_min, double y_max, double z_min, double z_max, double t_min, double t_max)
 Set 4 dimensional coordinates of a rectangle for a given tree. More...
 
int RTreeDeleteRect (struct RTree_Rect *, int, struct RTree *)
 Delete an item from a R*-Tree. More...
 
void RTreePrintRect (struct RTree_Rect *, int, struct RTree *)
 
struct RTreeRTreeCreateTree (int, off_t, int)
 Create new empty R*-Tree. More...
 
void RTreeSetOverflow (struct RTree *, char)
 Enable/disable R*-tree forced reinsertion (overflow) More...
 
void RTreeDestroyTree (struct RTree *)
 Destroy an R*-Tree. More...
 
int RTreeOverlap (struct RTree_Rect *, struct RTree_Rect *, struct RTree *)
 
int RTreeContained (struct RTree_Rect *, struct RTree_Rect *, struct RTree *)
 
int RTreeContains (struct RTree_Rect *, struct RTree_Rect *, struct RTree *)
 
struct RTree_NodeRTreeAllocNode (struct RTree *, int)
 
void RTreeInitNode (struct RTree *, struct RTree_Node *, int)
 
void RTreeCopyNode (struct RTree_Node *, struct RTree_Node *, struct RTree *)
 
void RTreeFreeNode (struct RTree_Node *)
 
void RTreeDestroyNode (struct RTree_Node *, int)
 
struct RTree_RectRTreeAllocRect (struct RTree *t)
 Create a new rectangle for a given tree. More...
 
void RTreeFreeRect (struct RTree_Rect *r)
 Delete a rectangle. More...
 
RectRealRTreeAllocBoundary (struct RTree *t)
 Allocate the boundary array of a rectangle for a given tree. More...
 
void RTreeFreeBoundary (struct RTree_Rect *r)
 Delete the boundary of a rectangle. More...
 
size_t RTreeReadNode (struct RTree_Node *, off_t, struct RTree *)
 
size_t RTreeWriteNode (struct RTree_Node *, struct RTree *)
 
off_t RTreeGetNodePos (struct RTree *)
 
void RTreeFlushBuffer (struct RTree *)
 

Macro Definition Documentation

◆ FALSE

#define FALSE   0

Definition at line 36 of file rtree.h.

◆ LEAFCARD

#define LEAFCARD   MAXCARD

Definition at line 46 of file rtree.h.

◆ MAXCARD

#define MAXCARD   9

Definition at line 44 of file rtree.h.

◆ MAXLEVEL

#define MAXLEVEL   20 /* 8^MAXLEVEL items are guaranteed to fit into the tree */

Definition at line 49 of file rtree.h.

◆ NODE_BUFFER_SIZE

#define NODE_BUFFER_SIZE   32

Definition at line 52 of file rtree.h.

◆ NODECARD

#define NODECARD   MAXCARD

Definition at line 45 of file rtree.h.

◆ TRUE

#define TRUE   1

Definition at line 33 of file rtree.h.

Typedef Documentation

◆ RectReal

typedef double RectReal

Definition at line 26 of file rtree.h.

◆ rt_delete_fn

typedef int rt_delete_fn(struct RTree_Rect *, union RTree_Child, struct RTree *)

Definition at line 94 of file rtree.h.

◆ rt_insert_fn

typedef int rt_insert_fn(struct RTree_Rect *, union RTree_Child, int, struct RTree *)

Definition at line 92 of file rtree.h.

◆ rt_search_fn

typedef int rt_search_fn(struct RTree *, struct RTree_Rect *, SearchHitCallback *, void *)

Definition at line 90 of file rtree.h.

◆ rt_valid_child_fn

typedef int rt_valid_child_fn(union RTree_Child *)

Definition at line 96 of file rtree.h.

◆ SearchHitCallback

typedef int SearchHitCallback(int id, const struct RTree_Rect *rect, void *arg)

Definition at line 86 of file rtree.h.

Function Documentation

◆ RTreeAllocBoundary()

RectReal* RTreeAllocBoundary ( struct RTree t)

Allocate the boundary array of a rectangle for a given tree.

This method allocated the boundary coordinates array in provided rectangle. It does not release previously allocated memory.

Parameters
rThe pointer to rectangle to initialize the boundary coordinates. This is usually a rectangle that was created on the stack or self allocated.
tThe pointer to a RTree struct

Definition at line 81 of file rect.c.

References assert, RTree_Rect::boundary, malloc(), and t.

Referenced by RTreeAllocNode(), RTreeAllocRect(), and RTreeCreateTree().

◆ RTreeAllocNode()

struct RTree_Node* RTreeAllocNode ( struct RTree t,
int  level 
)

◆ RTreeAllocRect()

struct RTree_Rect* RTreeAllocRect ( struct RTree t)

Create a new rectangle for a given tree.

This method allocates a new rectangle and initializes the internal boundary coordinates based on the tree dimension.

Hence a call to RTreeNewBoundary() is not necessary.

Parameters
tThe pointer to a RTree struct
Returns
A new allocated RTree_Rect struct

Definition at line 42 of file rect.c.

References assert, malloc(), r, RTreeAllocBoundary(), and t.

◆ RTreeContained()

int RTreeContained ( struct RTree_Rect r,
struct RTree_Rect s,
struct RTree t 
)

Definition at line 609 of file rect.c.

◆ RTreeContains()

int RTreeContains ( struct RTree_Rect r,
struct RTree_Rect s,
struct RTree t 
)

Definition at line 634 of file rect.c.

◆ RTreeCopyNode()

void RTreeCopyNode ( struct RTree_Node n1,
struct RTree_Node n2,
struct RTree t 
)

◆ RTreeCreateTree()

struct RTree* RTreeCreateTree ( int  fd,
off_t  rootpos,
int  ndims 
)

Create new empty R*-Tree.

This method creates a new RTree, either in memory (fd < 0) or in file. If the file descriptor is positive, the corresponding file must have been opened for reading and writing. This method must also be called if an existing tree previously saved to file is going to be accessed.

Parameters
fdfile descriptor to hold data, negative toggles memory mode
rootposoffset in file to root node (past any header info)
ndimsnumber of dimensions for the new tree: min 2, max 20
Returns
pointer to new RTree structure

Definition at line 61 of file vector/rtree/index.c.

References RTree::_recycle::alloc, RTree::_recycle::avail, RTree_Rect::boundary, RTree_Node::branch, RTree::BranchBuf, RTree::branchsize, RTree::c, RTree::center_n, RTree_PartitionVars::cover, RTree::delete_rect, NodeBuffer::dirty, RTree::fd, RTree::free_nodes, RTree::insert_rect, RTree::leafcard, RTree_Node::level, malloc(), MAXCARD, MAXLEVEL, RTree::min_leaf_fill, RTree::min_node_fill, RTree::minfill_leaf_split, RTree::minfill_node_split, NodeBuffer::n, RTree::n_leafs, RTree::n_nodes, RTree::nb, RTree::ndims, RTree::ndims_alloc, NODE_BUFFER_SIZE, RTree::nodecard, RTree::nodesize, RTree::ns, RTree::nsides, RTree::nsides_alloc, NULL, RTree::orect, RTree::overflow, RTree::p, NodeBuffer::pos, RTree::_recycle::pos, RTree_Branch::rect, RTree::rectsize, RTree::root, RTree::rootlevel, RTree::rootpos, RTreeAllocBoundary(), RTreeAllocNode(), RTreeDeleteRectF(), RTreeDeleteRectM(), RTreeFreeNode(), RTreeInsertRectF(), RTreeInsertRectM(), RTreeSearchF(), RTreeSearchM(), RTreeValidChildF(), RTreeValidChildM(), RTreeWriteNode(), RTree::search_rect, RTree::used, and RTree::valid_child.

Referenced by Vect_spatial_index_init().

◆ RTreeDeleteRect()

int RTreeDeleteRect ( struct RTree_Rect r,
int  tid,
struct RTree t 
)

Delete an item from a R*-Tree.

This method deletes an item from the RTree. The rectangle passed to this method does not need to be the exact rectangle, the only requirement is that this rectangle overlaps with the rectangle to be deleted. The rectangle to be deleted is identified by its id.

Parameters
rpointer to rectangle to use for searching
tidid of the data to be deleted, must be > 0
tpointer to RTree structure
Returns
0 on success
1 if data item not found

Definition at line 347 of file vector/rtree/index.c.

References assert, RTree_Child::id, r, and t.

Referenced by dig_spidx_del_area(), dig_spidx_del_isle(), dig_spidx_del_node(), and Vect_spatial_index_del_item().

◆ RTreeDestroyNode()

void RTreeDestroyNode ( struct RTree_Node n,
int  nodes 
)

◆ RTreeDestroyTree()

void RTreeDestroyTree ( struct RTree t)

Destroy an R*-Tree.

This method releases all memory allocated to a RTree. It deletes all rectangles and all memory allocated for internal support data. Note that for a file-based RTree, the file is not deleted and not closed. The file can thus be used to permanently store an RTree.

Parameters
tpointer to RTree structure
Returns
nothing

Definition at line 227 of file vector/rtree/index.c.

References assert, free(), MAXCARD, MAXLEVEL, NODE_BUFFER_SIZE, RTreeDestroyNode(), RTreeFreeBoundary(), and t.

Referenced by dig_spidx_free(), and Vect_spatial_index_destroy().

◆ RTreeFlushBuffer()

void RTreeFlushBuffer ( struct RTree t)

Definition at line 233 of file io.c.

References NODE_BUFFER_SIZE, RTreeRewriteNode(), and t.

◆ RTreeFreeBoundary()

void RTreeFreeBoundary ( struct RTree_Rect r)

Delete the boundary of a rectangle.

This method deletes (free) the memory of the boundary of a rectangle and sets the boundary pointer to NULL.

Parameters
rThe pointer to the rectangle to delete the boundary from.

Definition at line 98 of file rect.c.

References assert, free(), NULL, and r.

Referenced by RTreeDestroyTree(), RTreeFreeListBranch(), RTreeFreeNode(), and RTreeFreeRect().

◆ RTreeFreeNode()

void RTreeFreeNode ( struct RTree_Node n)

Definition at line 95 of file node.c.

References assert, RTree_Node::branch, free(), MAXCARD, RTree_Branch::rect, and RTreeFreeBoundary().

Referenced by RTreeCreateTree(), and RTreeDestroyNode().

◆ RTreeFreeRect()

void RTreeFreeRect ( struct RTree_Rect r)

Delete a rectangle.

This method deletes (free) the allocated memory of a rectangle.

Parameters
rThe pointer to the rectangle to be deleted

Definition at line 63 of file rect.c.

References assert, free(), r, and RTreeFreeBoundary().

◆ RTreeGetNodePos()

off_t RTreeGetNodePos ( struct RTree t)

Definition at line 71 of file io.c.

References t.

◆ RTreeInitNode()

void RTreeInitNode ( struct RTree t,
struct RTree_Node n,
int  type 
)

Definition at line 62 of file node.c.

◆ RTreeInsertRect()

int RTreeInsertRect ( struct RTree_Rect r,
int  tid,
struct RTree t 
)

Insert an item into a R*-Tree.

Parameters
rpointer to rectangle to use for searching
tiddata id stored with rectangle, must be > 0
tpointer to RTree structure
Returns
number of qualifying data rectangles

Definition at line 320 of file vector/rtree/index.c.

References assert, RTree_Child::id, r, and t.

Referenced by dig_spidx_add_area(), dig_spidx_add_isle(), dig_spidx_add_node(), and Vect_spatial_index_add_item().

◆ RTreeOverlap()

int RTreeOverlap ( struct RTree_Rect r,
struct RTree_Rect s,
struct RTree t 
)

Definition at line 590 of file rect.c.

◆ RTreePrintRect()

void RTreePrintRect ( struct RTree_Rect R,
int  depth,
struct RTree t 
)

Definition at line 304 of file rect.c.

◆ RTreeReadNode()

size_t RTreeReadNode ( struct RTree_Node n,
off_t  nodepos,
struct RTree t 
)

Definition at line 94 of file io.c.

References RTree_Node::branch, RTree_Node::count, RTree_Node::level, MAXCARD, RTreeReadBranch(), and t.

Referenced by RTreeGetNode().

◆ RTreeSearch()

int RTreeSearch ( struct RTree t,
struct RTree_Rect r,
SearchHitCallback shcb,
void *  cbarg 
)

Search an R*-Tree.

Search in an RTree for all data rectangles that overlap or touch the argument rectangle. Return the number of qualifying data rectangles. The search stops if the SearchHitCallBack function returns 0 (zero) or if there are no more qualifying data rectangles.

Parameters
tpointer to RTree structure
rpointer to rectangle to use for searching
shcbSearch Hit CallBack function
cbargcustom pointer used as argument for the shcb fn
Returns
number of qualifying data rectangles

Definition at line 303 of file vector/rtree/index.c.

References assert, r, and t.

Referenced by dig_find_area_box(), dig_find_isle_box(), dig_find_node(), dig_select_areas(), dig_select_isles(), dig_select_lines(), dig_select_nodes(), and Vect_spatial_index_select().

◆ RTreeSetOverflow()

void RTreeSetOverflow ( struct RTree t,
char  overflow 
)

Enable/disable R*-tree forced reinsertion (overflow)

For dynamic R*-trees with runtime insertion and deletion, forced reinsertion results in a more compact tree, searches are a bit faster. For static R*-trees (no insertion/deletion after creation) forced reinsertion can be disabled at the cost of slower searches.

Parameters
tpointer to RTree structure
overflowbinary flag
Returns
nothing

Definition at line 209 of file vector/rtree/index.c.

References t.

◆ RTreeSetRect1D()

void RTreeSetRect1D ( struct RTree_Rect r,
struct RTree t,
double  x_min,
double  x_max 
)

Set one dimensional coordinates of a rectangle for a given tree.

All coordinates of the rectangle will be initialized to 0 before the x coordinates are set.

Parameters
rThe pointer to the rectangle
tThe pointer to the RTree
x_minThe lower x coordinate
x_maxThe higher x coordinate

Definition at line 128 of file rect.c.

References r, RTreeInitRect(), and t.

◆ RTreeSetRect2D()

void RTreeSetRect2D ( struct RTree_Rect r,
struct RTree t,
double  x_min,
double  x_max,
double  y_min,
double  y_max 
)

Set two dimensional coordinates of a rectangle for a given tree.

All coordinates of the rectangle will be initialized to 0 before the x and y coordinates are set.

Parameters
rThe pointer to the rectangle
tThe pointer to the RTree
x_minThe lower x coordinate
x_maxThe higher x coordinate
y_minThe lower y coordinate
y_maxThe higher y coordinate

Definition at line 149 of file rect.c.

References r, RTreeInitRect(), and t.

◆ RTreeSetRect3D()

void RTreeSetRect3D ( struct RTree_Rect r,
struct RTree t,
double  x_min,
double  x_max,
double  y_min,
double  y_max,
double  z_min,
double  z_max 
)

Set three dimensional coordinates of a rectangle for a given tree.

All coordinates of the rectangle will be initialized to 0 before the x,y and z coordinates are set.

Parameters
rThe pointer to the rectangle
tThe pointer to the RTree
x_minThe lower x coordinate
x_maxThe higher x coordinate
y_minThe lower y coordinate
y_maxThe higher y coordinate
z_minThe lower z coordinate
z_maxThe higher z coordinate

Definition at line 174 of file rect.c.

References r, RTreeInitRect(), and t.

◆ RTreeSetRect4D()

void RTreeSetRect4D ( struct RTree_Rect r,
struct RTree t,
double  x_min,
double  x_max,
double  y_min,
double  y_max,
double  z_min,
double  z_max,
double  t_min,
double  t_max 
)

Set 4 dimensional coordinates of a rectangle for a given tree.

All coordinates of the rectangle will be initialized to 0 before the x,y,z and t coordinates are set.

Parameters
rThe pointer to the rectangle
tThe pointer to the RTree
x_minThe lower x coordinate
x_maxThe higher x coordinate
y_minThe lower y coordinate
y_maxThe higher y coordinate
z_minThe lower z coordinate
z_maxThe higher z coordinate
t_minThe lower t coordinate
t_maxThe higher t coordinate

Definition at line 204 of file rect.c.

References assert, r, RTreeInitRect(), and t.

◆ RTreeWriteNode()

size_t RTreeWriteNode ( struct RTree_Node n,
struct RTree t 
)