Geospatial Processor Tutorial

An educational tutorial package for geospatial data processing, focusing on road segment mapping and lane boundary analysis. This project provides hands-on examples and implementations for working with geospatial road data using Python.

🌐 Try the Interactive Demo - See the tutorial in action!

🎯 Purpose

This project is designed as an educational resource for:s the d

• Students learning geospatial data processing concepts
• Developers new to GIS and road data analysis
• Researchers working with transportation datasets
• Engineers building mapping and navigation systems

🚀 Features

• Complete Processing Pipeline: Load, validate, and process geospatial road data
• Spatial Indexing: Efficient R-tree spatial indexing for fast geometric queries
• Road Edge Detection: Automatic detection of lane boundaries and road edges
• Visualization Tools: Built-in plotting and analysis capabilities
• Error Handling: Comprehensive error handling and logging
• Sample Data: Included test datasets for immediate experimentation
• Interactive Tutorial: Step-by-step explanations with visual examples

📦 Installation

From Source (Recommended for Learning)

# Clone the repository
git clone https://gitlab.com/ananno/geospatial-processing.git
cd geospatial-processing

# Install in development mode
pip install -e .

# Or install with development dependencies
pip install -e ".[dev]"

Using pip

pip install geospatial-processor

🏃 Quick Start

1. Basic Usage

from geospatial_processor import GeospatialProcessor
from geospatial_processor.core.config import ProcessingConfig

# Configure the processor
config = ProcessingConfig(
    tolerance=0.1,
    road_width_estimate=3.5,
    output_dir="./output"
)

# Initialize processor
processor = GeospatialProcessor(config)

# Load your data
centerlines, lanes = processor.load_data(
    "path/to/centerlines.geojson",
    "path/to/lanes.geojson"
)

# Build spatial index
processor.build_spatial_index(lanes)

# Detect road edges
road_edges = processor.detect_road_edges(centerlines, lanes)

# Process and create outputs
processor.create_sample_output(road_slices)

2. Run the Demo

# Run with sample data
python examples/basic_usage.py

# Or use the installed command
geospatial-demo

3. Interactive Web Demo

Visit the live interactive tutorial at: 🌐 https://ananno.gitlab.io/geospatial-processing

This web demo provides a step-by-step walkthrough of the entire processing pipeline with visualizations and code examples.

4. Interactive Tutorial

from geospatial_processor.tutorial import GeospatialTutorial

# Create tutorial instance
tutorial = GeospatialTutorial()

# Run step-by-step examples
tutorial.create_sample_data()
tutorial.demonstrate_spatial_indexing()
tutorial.show_road_edge_detection()

📁 Project Structure

geospatial-processor/
├── geospatial_processor/           # Main package
│   ├── __init__.py                 # Package initialization
│   ├── core/                       # Core processing modules
│   │   ├── __init__.py
│   │   ├── processor.py            # Main processing logic
│   │   └── config.py               # Configuration classes
│   ├── tutorial/                   # Tutorial specific code
│   │   ├── __init__.py
│   │   └── tutorial.py             # Interactive tutorial
│   └── utils/                      # Utility functions
│       ├── __init__.py
│       └── helpers.py
├── examples/                       # Example scripts
│   └── basic_usage.py              # Basic usage example
├── docs/                          # Documentation
│   ├── tutorial.md                # Comprehensive tutorial
│   └── summary.md                 # Processing summary
├── data/                          # Sample data
│   ├── input/                     # Input GeoJSON files
│   │   ├── groups.geojson         # Sample centerlines
│   │   └── lanes.geojson          # Sample lane boundaries
│   └── output/                    # Output directory
├── web_demo/                      # Web visualization demo
│   └── demo.tsx                   # React component demo
├── assets/                        # Images and visualizations
├── tests/                         # Test files
├── pyproject.toml                 # Project configuration
├── README.md                      # This file
└── LICENSE                        # MIT license

🗺️ Understanding the Data

Input Data Format

The processor expects two GeoJSON files:

1. Centerlines (groups.geojson): Road centerlines with properties

   {
     "type": "Feature",
     "geometry": {"type": "LineString", "coordinates": [[x1, y1], [x2, y2]]},
     "properties": {
       "id": "centerline_1",
       "left_boundary_id": "boundary_1",
       "right_boundary_id": "boundary_2",
       "lane_count": 2
     }
   }
   

2. Lane Boundaries (lanes.geojson): Lane boundary lines

   {
     "type": "Feature",
     "geometry": {"type": "LineString", "coordinates": [[x1, y1], [x2, y2]]},
     "properties": {
       "id": "boundary_1",
       "type": "solid_white",
       "source": "re"  # 're' for road edges
     }
   }
   

Output Data

• Processing Summary: JSON file with statistics and timing
• Visualization: PNG charts showing processing results
• Sample GeoJSON: Processed road slices for visualization

🎓 Learning Path

1. Start with the Tutorial: Read docs/tutorial.md for conceptual understanding
2. Run Basic Example: Execute examples/basic_usage.py
3. Explore the Code: Study geospatial_processor/core/processor.py
4. Try Your Own Data: Replace sample data with your own GeoJSON files
5. Extend Functionality: Add new processing features

🔧 Development

Setting up Development Environment

# Clone and install in development mode
git clone https://gitlab.com/ananno/geospatial-processing.git
cd geospatial-processing
pip install -e ".[dev]"

# Run tests
pytest

# Format code
black geospatial_processor/

# Lint code
flake8 geospatial_processor/

# Type checking
mypy geospatial_processor/

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Commit your changes (git commit -m 'Add amazing feature')
7. Push to the branch (git push origin feature/amazing-feature)
8. Open a Pull Request

📚 Documentation

• Complete Tutorial: Comprehensive guide with theory and examples
• API Reference: Detailed API documentation
• Web Demo: Interactive React component for visualization

🧪 Dependencies

Core Dependencies

• geopandas: Geospatial data manipulation
• shapely: Geometric operations
• rtree: Spatial indexing
• networkx: Graph processing
• matplotlib & seaborn: Visualization
• pandas & numpy: Data processing

Development Dependencies

• pytest: Testing framework
• black: Code formatting
• flake8: Linting
• mypy: Type checking

📊 Performance

The processor is optimized for educational use with moderate-sized datasets:

• Spatial Indexing: O(log n) query performance using R-tree
• Memory Efficient: Chunked processing for large datasets
• Error Resilient: Comprehensive error handling and logging
• Configurable: Adjustable parameters for different use cases

🤝 Support

• Issues: GitLab Issues
• Discussions: GitLab Discussions
• Email: ananno@pm.me

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• GeoPandas Community for excellent geospatial tools
• Shapely for geometric operations
• Educational GIS Resources that inspired this tutorial
• Open Source Community for making geospatial analysis accessible

🎯 Future Enhancements

• Support for additional input formats (KML, Shapefile)
• Advanced lane detection algorithms
• 3D road modeling capabilities
• Integration with mapping services
• Performance optimizations for large datasets
• Interactive Jupyter notebook tutorials
• Command-line interface
• Docker containerization

---

Happy Learning! 🚀

This project aims to make geospatial processing approachable and fun. Whether you're analyzing city streets or highway networks, this tutorial provides the foundation you need to work with real-world road data.