Skip to content
HeliosDB HeliosDB Full

HeliosDB Geospatial Package - Complete Summary

HeliosDB Geospatial Package - Complete Summary

Package Overview

Package Name: heliosdb-geospatial Version: 3.0.0 Purpose: PostGIS-compatible geospatial data types and functions for HeliosDB v3.0

Package Structure

heliosdb-geospatial/
├── Cargo.toml                          # Package configuration and dependencies
├── README.md                           # User documentation
├── PACKAGE_SUMMARY.md                  # This file
│
├── src/
│   ├── lib.rs                         # Package entry point and public API
│   ├── error.rs                       # Error types and Result alias
│   ├── types.rs                       # Geometry type definitions
│   ├── functions.rs                   # PostGIS-compatible ST_* functions
│   ├── rtree.rs                       # R-tree spatial index implementation
│   ├── wkt.rs                         # WKT parsing and formatting
│   ├── wkb.rs                         # WKB encoding and decoding
│   └── projections.rs                 # Coordinate transformations (SRID support)
│
├── examples/
│   ├── basic_usage.rs                 # Basic geometry operations
│   ├── spatial_index.rs               # R-tree indexing and queries
│   ├── wkt_wkb.rs                     # Text and binary formats
│   └── projections.rs                 # Coordinate transformations
│
├── tests/
│   └── integration_test.rs            # Comprehensive integration tests
│
└── benches/
    └── spatial_operations.rs          # Performance benchmarks

Core Components

1. Cargo.toml

Lines: 60 Dependencies:

  • geo, geo-types - Core geometry algorithms
  • rstar - R-tree spatial indexing
  • proj - Coordinate transformations
  • wkt, wkb - Format support
  • serde - Serialization
  • thiserror, anyhow - Error handling
  • byteorder - Binary encoding

2. lib.rs (Package Entry Point)

Lines: 67 Exports:

  • All geometry types (Point, LineString, Polygon, etc.)
  • All spatial functions
  • Spatial index types
  • Error types
  • Constants (WGS84_SRID, WEB_MERCATOR_SRID)

3. error.rs (Error Handling)

Lines: 50 Features:

  • GeospatialError enum with 11 error variants
  • Result<T> type alias
  • Auto-conversion from external error types
  • Comprehensive error messages

4. types.rs (Geometry Types)

Lines: 350 Geometry Types:

  • Point - 2D point with optional SRID
  • LineString - Sequence of connected points
  • Polygon - Exterior ring with optional holes
  • MultiPoint - Collection of points
  • MultiLineString - Collection of linestrings
  • MultiPolygon - Collection of polygons
  • GeometryCollection - Heterogeneous collection
  • Geography - Spherical geometry type

Features:

  • SRID support on all types
  • Conversion to/from geo-types
  • Serialization support
  • Type accessors and mutators

5. functions.rs (Spatial Functions)

Lines: 450 Function Categories:

Measurement Functions (6)

  • st_distance - Euclidean distance
  • st_distance_spheroid - Haversine distance
  • st_length - Linear length
  • st_area - Polygon area
  • st_perimeter - Polygon perimeter
  • haversine_distance - Spherical distance helper

Spatial Relationships (7)

  • st_contains - Containment test
  • st_within - Inverse containment
  • st_intersects - Intersection test
  • st_disjoint - Disjoint test
  • st_touches - Touch test
  • st_overlaps - Overlap test
  • st_equals - Equality test

Geometry Processing (7)

  • st_centroid - Calculate centroid
  • st_envelope - Bounding box
  • st_convex_hull - Convex hull
  • st_simplify - Douglas-Peucker simplification
  • st_simplify_preserve_topology - Visvalingam-Whyatt
  • st_buffer - Buffer generation
  • Various geometry constructors

Accessors (8)

  • st_x, st_y - Coordinate getters
  • st_npoints - Point count
  • st_srid, st_set_srid - SRID management
  • st_geometry_type - Type name
  • st_is_empty - Emptiness test
  • st_is_valid - Validity test

Total: 30+ functions

6. rtree.rs (R-tree Spatial Index)

Lines: 350 Components:

  • SpatialObject - Indexed geometry wrapper
  • SpatialIndex - Main R-tree index
  • SpatialIndexBuilder - Bulk loading builder
  • spatial_join - Join operation

Features:

  • O(log n) insertion
  • O(log n + k) bounding box queries
  • K-Nearest Neighbor search
  • KNN with distance limits
  • Bulk loading optimization
  • SRID validation
  • Spatial join operations

7. wkt.rs (Well-Known Text)

Lines: 400 Functions:

  • parse_wkt - Parse WKT string to Geometry
  • parse_wkt_with_srid - Parse with SRID prefix
  • to_wkt - Format Geometry as WKT
  • Internal parsers for all geometry types

Supported Formats:

  • POINT(x y)
  • LINESTRING(x1 y1, x2 y2, ...)
  • POLYGON((x1 y1, ...), (hole1), ...)
  • MULTIPOINT(x1 y1, ...)
  • MULTILINESTRING((...),...)
  • MULTIPOLYGON(((...)...),...)
  • GEOMETRYCOLLECTION(...)
  • SRID=4326;POINT(x y)

8. wkb.rs (Well-Known Binary)

Lines: 550 Components:

  • WKBType enum - Geometry type codes
  • ByteOrder enum - Endianness control
  • to_wkb - Encode to binary
  • from_wkb - Decode from binary
  • from_wkb_with_srid - Decode with SRID

Features:

  • Big-endian and little-endian support
  • Efficient binary encoding
  • OGC WKB specification compliant
  • All geometry types supported

9. projections.rs (Coordinate Transformations)

Lines: 350 Components:

  • ProjectionTransformer - Main transformer with cache
  • transform_to_wgs84 - Helper for WGS84
  • transform_to_web_mercator - Helper for Web Mercator
  • calculate_bounds - Bounding box calculation
  • get_center - Center point calculation

Supported SRIDs:

  • 4326 (WGS84 - Geographic)
  • 3857 (Web Mercator - Projected)
  • 4269 (NAD83)
  • 32601-32660 (UTM Northern Hemisphere)
  • 32701-32760 (UTM Southern Hemisphere)
  • 4258 (ETRS89)
  • 27700 (British National Grid)
  • Any EPSG code via PROJ library

Examples

1. basic_usage.rs

Lines: 150 Demonstrates:

  • Point distance calculations
  • LineString operations
  • Polygon area and perimeter
  • Spatial relationships
  • Geometry processing
  • Geographic distance (spheroid)

2. spatial_index.rs

Lines: 200 Demonstrates:

  • Basic index operations
  • Bounding box queries
  • K-Nearest Neighbor search
  • Bulk loading
  • Spatial join operations

3. wkt_wkb.rs

Lines: 180 Demonstrates:

  • WKT parsing and formatting
  • WKT with SRID
  • Complex geometries
  • WKB encoding/decoding
  • Byte order handling
  • WKB with SRID

4. projections.rs

Lines: 160 Demonstrates:

  • WGS84 to Web Mercator
  • Web Mercator to WGS84
  • Polygon transformation
  • Bounds calculation
  • Center point calculation
  • Multiple transformations

Tests

integration_test.rs

Lines: 450 Test Coverage:

  • All geometry types
  • All spatial functions
  • Spatial index operations
  • WKT parsing and formatting
  • WKB encoding and decoding
  • Coordinate transformations
  • SRID validation
  • Geography type
  • Error handling

Total Tests: 30+

Benchmarks

spatial_operations.rs

Lines: 250 Benchmarks:

  • Distance calculations (Euclidean, Spheroid)
  • Area and perimeter
  • Spatial relationships
  • R-tree operations (insert, bulk load, query)
  • WKT parsing and formatting
  • WKB encoding and decoding

Benchmark Groups: 6

Performance Characteristics

R-tree Index

  • Insertion: O(log n)
  • Bounding Box Query: O(log n + k) where k = results
  • KNN Search: O(k log n)
  • Bulk Loading: O(n log n) with optimized structure

Spatial Functions

  • Distance: O(1) for points, O(n) for complex geometries
  • Contains: O(log n) average case
  • Intersects: O(n) for polygon-polygon
  • Centroid: O(n) where n = vertices
  • Buffer: O(n * segments)

Format Conversion

  • WKT Parsing: O(n) where n = string length
  • WKT Formatting: O(n) where n = coordinates
  • WKB Encoding: O(n) where n = coordinates
  • WKB Decoding: O(n) where n = bytes

Features Flags

  • default: Enables rtree and projections
  • rtree: R-tree spatial indexing
  • projections: Coordinate transformations
  • serde: Serialization support

Total Code Statistics

ComponentFilesLinesPurpose
Core Source8~2,500Main implementation
Examples4~650Usage demonstrations
Tests1~450Integration testing
Benchmarks1~250Performance testing
Documentation2~400User guides
Total16~4,250Complete package

Key Features Summary

Geometry Types: 7 OGC-compliant types Spatial Functions: 30+ PostGIS-compatible functions Spatial Indexing: R-tree with KNN search Format Support: WKT and WKB Projections: Full SRID transformation support Geography: Spherical calculations Performance: Optimized algorithms and bulk loading Testing: Comprehensive test coverage Examples: 4 detailed examples Benchmarks: Performance tracking

Usage Example

use heliosdb_geospatial::{Point, Geometry, functions::*};


// Create points with SRID
let sf = Point::new(-122.4194, 37.7749, Some(4326));
let la = Point::new(-118.2437, 34.0522, Some(4326));


// Calculate spherical distance
let distance = st_distance_spheroid(
    &Geometry::Point(sf),
    &Geometry::Point(la)
).unwrap();


println!("Distance: {} km", distance / 1000.0);

Integration with HeliosDB

This package provides the foundation for:

  • Geospatial column types (GEOMETRY, GEOGRAPHY)
  • Spatial indexing strategies
  • Geospatial query functions
  • Spatial join operations
  • GIS data import/export

License

MIT OR Apache-2.0