Configuration and Properties

class Property:
    def __init__(self, handle=None, owned: bool = True, **kwargs: Any) -> None:
        """
        Create a property configuration object.
        
        Parameters:
        - handle (optional): Internal handle (for advanced use)
        - owned (bool): Handle ownership flag
        - **kwargs: Property values to set during initialization
        
        Returns:
        None
        """
    
    def initialize_from_dict(self, state: dict[str, Any]) -> None:
        """
        Initialize properties from a dictionary.
        
        Parameters:
        - state (dict): Dictionary of property name-value pairs
        
        Returns:
        None
        """
    
    def as_dict(self) -> dict[str, Any]:
        """
        Convert properties to a dictionary representation.
        
        Returns:
        dict: All property values as key-value pairs
        """

class Property:
    type: int
    """
    Index type selection.
    
    Values:
    - RT_RTree (0): Standard R-Tree (default, recommended)
    - RT_MVRTree (1): Multi-Version R-Tree
    - RT_TPRTree (2): Time-Parameterized R-Tree for moving objects
    """
    
    variant: int  
    """
    Index variant for node splitting algorithm.
    
    Values:
    - RT_Linear (0): Linear splitting (fastest)
    - RT_Quadratic (1): Quadratic splitting (balanced)
    - RT_Star (2): R*-Tree splitting (best quality, slower)
    """

from rtree import index

# Configure R*-Tree with quadratic splitting
p = index.Property()
p.type = index.RT_RTree
p.variant = index.RT_Star

idx = index.Index(properties=p)

class Property:
    storage: int
    """
    Storage backend type.
    
    Values:
    - RT_Memory (0): Memory-only storage (default)
    - RT_Disk (1): File-based storage  
    - RT_Custom (2): Custom storage implementation
    """
    
    filename: str
    """
    Base filename for disk storage (without extension).
    
    Used when storage = RT_Disk. Index creates .idx and .dat files.
    """
    
    dat_extension: str
    """
    File extension for data files (default: "dat").
    """
    
    idx_extension: str
    """
    File extension for index files (default: "idx").
    """
    
    overwrite: bool
    """
    Whether to overwrite existing files (default: False).
    
    If False and files exist, opens existing index.
    If True, creates new index, deleting existing files.
    """
    
    writethrough: bool
    """
    Enable write-through mode for immediate disk writes.
    
    If True, changes are written immediately to disk.
    If False, changes may be buffered.
    """

from rtree import index

# Configure disk-based storage
p = index.Property()
p.storage = index.RT_Disk
p.filename = "spatial_index"
p.overwrite = True
p.writethrough = True

idx = index.Index(properties=p)
# Creates spatial_index.idx and spatial_index.dat files

class Property:
    dimension: int
    """
    Number of spatial dimensions (default: 2).
    
    Common values:
    - 2: 2D spatial indexing (x, y coordinates)
    - 3: 3D spatial indexing (x, y, z coordinates)  
    - Higher: Multi-dimensional indexing
    
    Note: Must be set before index creation.
    """

from rtree import index

# Configure 3D spatial indexing
p = index.Property()
p.dimension = 3

idx = index.Index(properties=p)

# Insert 3D data: (minx, miny, minz, maxx, maxy, maxz)
idx.insert(0, (0, 0, 0, 1, 1, 1))

class Property:
    pagesize: int
    """
    Page size in bytes for disk storage (default: 4096).
    
    Larger values may improve performance for large datasets.
    Must be set before index creation.
    """
    
    index_capacity: int
    """
    Maximum number of entries per index node (default: 100).
    
    Higher values create wider, shallower trees.
    Lower values create narrower, deeper trees.
    """
    
    leaf_capacity: int  
    """
    Maximum number of entries per leaf node (default: 100).
    
    Affects query performance and storage efficiency.
    """
    
    fill_factor: float
    """
    Target fill factor for nodes (0.0 to 1.0).
    
    Controls how full nodes should be before splitting.
    Higher values improve storage efficiency but may hurt performance.
    """
    
    buffering_capacity: int
    """
    Buffer capacity for batched operations.
    
    Higher values can improve bulk operation performance.
    """

from rtree import index

# Performance tuning for large dataset
p = index.Property()
p.pagesize = 8192          # Larger pages
p.index_capacity = 200     # More entries per node
p.leaf_capacity = 200      # More entries per leaf
p.fill_factor = 0.9        # Pack nodes tightly
p.buffering_capacity = 1000 # Large buffer

idx = index.Index(properties=p)

class Property:
    point_pool_capacity: int
    """
    Capacity of the point object pool.
    
    Pre-allocates point objects to reduce memory allocation overhead.
    """
    
    region_pool_capacity: int
    """
    Capacity of the region object pool.
    
    Pre-allocates region objects to reduce memory allocation overhead.
    """
    
    index_pool_capacity: int
    """
    Capacity of the index object pool.
    
    Pre-allocates index node objects.
    """
    
    index_capacity: int
    """
    Maximum number of entries per index node.
    
    Controls the branching factor of internal nodes.
    Higher values create wider, shallower trees.
    """
    
    leaf_capacity: int
    """
    Maximum number of entries per leaf node.
    
    Controls how many data items are stored in each leaf.
    Affects both query performance and storage efficiency.
    """

class Property:
    near_minimum_overlap_factor: int
    """
    Factor for near minimum overlap splitting in R*-Tree.
    
    Controls the reinsertion strategy in R*-Tree variant.
    Lower values may improve query performance.
    """
    
    split_distribution_factor: float
    """
    Distribution factor for node splitting (0.0 to 1.0).
    
    Controls how evenly entries are distributed during splits.
    0.5 = even distribution, other values bias the distribution.
    """
    
    reinsert_factor: float
    """
    Reinsertion factor for R*-Tree forced reinsertion (0.0 to 1.0).
    
    Percentage of entries to reinsert during R*-Tree reorganization.
    """

class Property:
    tight_mbr: bool
    """
    Use tight minimum bounding rectangles (default: True).
    
    When True, computes exact bounding boxes.
    When False, may use loose bounding boxes for performance.
    """

class Property:
    custom_storage_callbacks: object
    """
    Custom storage callback functions.
    
    Pointer to callback structure for custom storage implementations.
    """
    
    custom_storage_callbacks_size: int
    """
    Size of custom storage callbacks structure.
    
    Must match the size of the callback structure.
    """

class Property:
    tpr_horizon: float
    """
    Time horizon for TPR-Tree trajectory prediction.
    
    Maximum time into the future for which trajectories are predicted.
    Only used when type = RT_TPRTree.
    """

from rtree import index

# Configure TPR-Tree for moving objects  
p = index.Property()
p.type = index.RT_TPRTree
p.tpr_horizon = 100.0
p.dimension = 2

tpr_idx = index.Index(properties=p)

class Property:
    index_id: int
    """
    Unique identifier for the index.
    
    Useful when working with multiple indexes or custom storage.
    """

from rtree import index
from rtree.exceptions import RTreeError

p = index.Property()

try:
    p.pagesize = -1000  # Invalid negative value
except RTreeError as e:
    print(f"Invalid property: {e}")

# Some properties are automatically adjusted for consistency
p.index_capacity = 50
p.leaf_capacity = 100  
p.near_minimum_overlap_factor = 75  # May be auto-adjusted if >= min(index_capacity, leaf_capacity)

from rtree import index

# Create and configure properties
p = index.Property()
p.dimension = 3
p.pagesize = 8192
p.index_capacity = 200

# Serialize to dictionary
prop_dict = p.as_dict()
print(prop_dict)

# Restore from dictionary
p2 = index.Property()
p2.initialize_from_dict(prop_dict)

from rtree import index

# Optimized for query performance
p = index.Property()
p.variant = index.RT_Star        # Best splitting quality
p.index_capacity = 50            # Smaller nodes for better queries
p.leaf_capacity = 50             # Smaller leaves
p.buffering_capacity = 10000     # Large buffer
p.tight_mbr = True              # Exact bounding boxes

idx = index.Index(properties=p)

from rtree import index

# Optimized for memory usage
p = index.Property()
p.variant = index.RT_Linear      # Fastest splitting
p.index_capacity = 200           # Larger nodes
p.leaf_capacity = 200            # Larger leaves  
p.fill_factor = 0.95            # Pack tightly
p.buffering_capacity = 100       # Small buffer

idx = index.Index(properties=p)

from rtree import index

# Optimized for large disk-based datasets
p = index.Property()
p.storage = index.RT_Disk
p.filename = "large_dataset"
p.pagesize = 16384              # Large pages
p.index_capacity = 500          # Very large nodes
p.leaf_capacity = 500           # Very large leaves
p.writethrough = False          # Buffer writes
p.overwrite = True              # Clean start

idx = index.Index(properties=p)