geoterminal 0.1.1

Geoterminal is a command-line tool designed to simplify common GIS tasks that you may encounter in your daily work.

Geoterminal

Geoterminal is a powerful Python library and command-line tool designed to streamline geospatial data processing and H3 grid operations. It provides an intuitive interface for common GIS operations, supporting multiple file formats and offering both a Python API and CLI for maximum flexibility.

Features

• Flexible Input/Output

  • Support for GeoJSON, Shapefile, CSV, ORC, and WKT formats
  • Direct WKT string input for quick operations
  • Automatic format detection and conversion

• Geometry Operations

  • Buffer creation with customizable distance
  • Geometry clipping with file or WKT mask
  • CRS transformation and validation

• H3 Integration

  • Convert geometries to H3 cells
  • Configurable resolution (0-15)
  • Optional geometry inclusion
  • Efficient spatial indexing

• Developer-Friendly

  • Clean Python API
  • Comprehensive CLI
  • Extensive documentation
  • Type hints and error handling

Quick Start

Installation

# Install from PyPI
pip install geoterminal

For development, we use Poetry. First install Poetry if you haven't already:

curl -sSL https://install.python-poetry.org | python3 -

Or if you have Homebrew installed, you can do:

brew install poetry

Then clone and install the project:

# Clone the repository
git clone https://github.com/jeronimoluza/geoterminal.git
cd geoterminal

# Install dependencies and create virtual environment
poetry install

# Install with development dependencies
poetry install --with dev

# Install with documentation dependencies
poetry install --with docs

# Activate the virtual environment
poetry shell

Usage

Basic Usage

Geoterminal accepts both file paths and WKT strings as input. The input and output file formats are automatically detected based on their extensions.

# Convert between different formats
geoterminal input.shp output.geojson
geoterminal input.geojson output.csv
geoterminal input.csv output.orc

# Generate from WKT string
geoterminal "POLYGON((30 10, 40 40, 20 40, 10 20, 30 10))" output.geojson

# Work with CSV/ORC files using custom geometry columns
geoterminal input.csv output.geojson --geometry-column my_wkt_column
geoterminal input.orc output.shp --geometry-column my_wkt_column

Processing Options

You can combine multiple processing options with your conversion commands:

# Apply a buffer of 1000 meters and convert to H3 cells
geoterminal input.shp output.geojson --buffer-size 1000 --h3-res 6

# Convert WKT to H3 cells with geometries
geoterminal "POLYGON((30 10, 40 40, 20 40, 10 20, 30 10))" output.geojson --h3-res 6 --h3-geom

# Reproject data
geoterminal input.shp output.csv --input-crs 4326 --output-crs 3857

# Clip geometries using a mask file
geoterminal input.shp output.geojson --mask mask.geojson --mask-crs 4326

# Clip geometries using a mask WKT
geoterminal input.shp output.geojson --mask "POLYGON((30 10, 40 40, 20 40, 10 20, 30 10))"

File Inspection

View the contents of your files using the head and tail commands:

# View first 10 rows of a file
geoterminal input.geojson --head --rows 10

# View last 8 rows of a file
geoterminal input.geojson --tail --rows 8

Python API

from geoterminal.geometry_operations import GeometryProcessor
from geoterminal.h3_operations import H3Processor
from geoterminal.file_io import read_geometry_file

# Read data
gdf = read_geometry_file("input.geojson")

# Geometry operations
processor = GeometryProcessor(gdf)
buffered = processor.apply_buffer(distance=1000)

# H3 operations
h3_processor = H3Processor(gdf)
h3_cells = h3_processor.polyfill(resolution=6)

# Export
h3_cells.to_file("output.geojson")

Documentation

Comprehensive documentation is available:

• Installation Guide
• Usage Guide
• API Reference
• CLI Documentation
• FAQ

Contributing

Contributions are welcome! Please read our Contributing Guide for details on our code of conduct and the process for submitting pull requests.

License

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