gemgis

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

GemGIS - Geospatial Data for Geological Modelling

GemGIS - 地质建模用地理空间数据

Quick Reference

快速参考

python

import gemgis as gg
import geopandas as gpd

python

import gemgis as gg
import geopandas as gpd

Load vector data

加载矢量数据

gdf = gpd.read_file('geology.shp')

Extract XYZ from geometry with elevation from DEM

从几何图形中提取XYZ坐标，并从DEM获取高程

interfaces = gg.vector.extract_xyz(gdf=gdf, dem='dem.tif')

Define model extent

定义模型范围

extent = [x_min, x_max, y_min, y_max]

Clip to extent

按范围裁剪数据

gdf_clipped = gg.vector.clip_by_extent(gdf=gdf, extent=extent)

undefined

gdf_clipped = gg.vector.clip_by_extent(gdf=gdf, extent=extent)

undefined

Key Modules

核心模块

Module	Purpose
`gemgis.vector`	Vector data processing, XYZ extraction
`gemgis.raster`	Raster/DEM processing, sampling, interpolation
`gemgis.utils`	Utility functions, extent management
`gemgis.postprocessing`	Model postprocessing

模块	用途
`gemgis.vector`	矢量数据处理、XYZ坐标提取
`gemgis.raster`	栅格/DEM处理、采样、插值
`gemgis.utils`	工具函数、范围管理
`gemgis.postprocessing`	模型后处理

Essential Operations

核心操作

Extract Interface Points

提取界面点

python

contacts = gpd.read_file('contacts.shp')
interfaces = gg.vector.extract_xyz(gdf=contacts, dem='dem.tif')
interfaces['formation'] = contacts['formation']

python

contacts = gpd.read_file('contacts.shp')
interfaces = gg.vector.extract_xyz(gdf=contacts, dem='dem.tif')
interfaces['formation'] = contacts['formation']

Returns DataFrame with X, Y, Z, formation columns

返回包含X、Y、Z、地层列的DataFrame

undefined

undefined

Extract Orientations

提取产状数据

python

measurements = gpd.read_file('structural_measurements.shp')
orientations = gg.vector.extract_xyz(gdf=measurements, dem='dem.tif')
orientations['dip'] = measurements['dip']
orientations['azimuth'] = measurements['strike'] + 90  # strike to dip direction
orientations['formation'] = measurements['formation']

python

measurements = gpd.read_file('structural_measurements.shp')
orientations = gg.vector.extract_xyz(gdf=measurements, dem='dem.tif')
orientations['dip'] = measurements['dip']
orientations['azimuth'] = measurements['strike'] + 90  # 走向转倾向方位角
orientations['formation'] = measurements['formation']

Sample DEM Along Profile

沿剖面采样DEM

python

profile = gg.raster.sample_from_raster(
    raster='dem.tif',
    line=[(500000, 5600000), (510000, 5605000)],
    n_samples=100
)

python

profile = gg.raster.sample_from_raster(
    raster='dem.tif',
    line=[(500000, 5600000), (510000, 5605000)],
    n_samples=100
)

Returns dict with 'distance' and 'Z' arrays

返回包含'distance'和'Z'数组的字典

undefined

undefined

Define Model Extent

定义模型范围

python

undefined

python

undefined

From coordinates

通过坐标定义

extent = gg.utils.set_extent( x_min=500000, x_max=510000, y_min=5600000, y_max=5610000 )

From GeoDataFrame bounds

通过GeoDataFrame边界定义

extent = gg.utils.set_extent_from_bounds(gdf)

undefined

extent = gg.utils.set_extent_from_bounds(gdf)

undefined

Clip Data to Extent

按范围裁剪数据

python

from shapely.geometry import box
extent_poly = box(500000, 5600000, 510000, 5610000)
gdf_clipped = gdf.clip(extent_poly)

python

from shapely.geometry import box
extent_poly = box(500000, 5600000, 510000, 5610000)
gdf_clipped = gdf.clip(extent_poly)

Or using gemgis

或使用GemGIS工具

gdf_clipped = gg.vector.clip_by_extent( gdf=gdf, extent=[500000, 510000, 5600000, 5610000] )

undefined

gdf_clipped = gg.vector.clip_by_extent( gdf=gdf, extent=[500000, 510000, 5600000, 5610000] )

undefined

CRS Conversion

CRS转换

python

undefined

python

undefined

Always work in projected CRS (meters) for modeling

建模时始终使用投影CRS（米制）

gdf_utm = gdf.to_crs('EPSG:32632') # UTM zone 32N

gdf_utm = gdf.to_crs('EPSG:32632') # UTM 32N带

Or use GemGIS utility

或使用GemGIS工具

gdf_utm = gg.vector.reproject(gdf, 'EPSG:32632')

undefined

gdf_utm = gg.vector.reproject(gdf, 'EPSG:32632')

undefined

Supported Formats

支持的格式

Format	Extension	Read	Write
Shapefile	.shp	Yes	Yes
GeoJSON	.geojson	Yes	Yes
GeoPackage	.gpkg	Yes	Yes
GeoTIFF	.tif	Yes	Yes
ASCII Grid	.asc	Yes	Yes

格式	扩展名	读取	写入
Shapefile	.shp	是	是
GeoJSON	.geojson	是	是
GeoPackage	.gpkg	是	是
GeoTIFF	.tif	是	是
ASCII Grid	.asc	是	是

Common CRS

常用CRS

EPSG	Description
4326	WGS84 (lat/lon)
32632	UTM Zone 32N
32633	UTM Zone 33N

EPSG	描述
4326	WGS84（经纬度）
32632	UTM 32N带
32633	UTM 33N带

When to Use vs Alternatives

适用场景与替代方案对比

Scenario	Recommendation
Prepare GIS data for GemPy modelling	GemGIS - purpose-built bridge between GIS and GemPy
General geospatial analysis in Python	geopandas + rasterio - more flexible, larger community
GUI-based geological map processing	QGIS - visual, interactive, plugin ecosystem
Extract XYZ + elevation from shapefiles and DEMs	GemGIS - one-liner with `extract_xyz()`
Complex raster analysis pipelines	rasterio + xarray - more control and scalability

Choose GemGIS when: You are building a GemPy model and need to convert GIS data (shapefiles, DEMs, geological maps) into GemPy-compatible inputs. It eliminates boilerplate for common spatial data preparation tasks.

Avoid GemGIS when: You need general-purpose GIS analysis (use geopandas directly), or your workflow does not involve GemPy (the tool is specifically designed for that pipeline).

场景	推荐方案
为GemPy建模准备GIS数据	GemGIS - 专为GIS与GemPy搭建的桥梁工具
Python中通用地理空间分析	geopandas + rasterio - 灵活性更高，社区更庞大
基于GUI的地质图处理	QGIS - 可视化、交互式，拥有插件生态系统
从shapefile和DEM中提取XYZ坐标与高程	GemGIS - 一行代码调用 `extract_xyz()` 即可完成
复杂栅格分析流水线	rasterio + xarray - 可控性与扩展性更强

选择GemGIS的场景：当你正在构建GemPy模型，需要将GIS数据（shapefile、DEM、地质图）转换为GemPy兼容的输入格式时。它能消除常见空间数据准备任务的冗余代码。

避免使用GemGIS的场景：当你需要通用GIS分析（直接使用geopandas），或者你的工作流不涉及GemPy（该工具是专为该流水线设计的）。

Common Workflows

常见工作流程

Prepare geospatial data for GemPy model

为GemPy模型准备地理空间数据

Load geological map (contacts, formations) with
```
gpd.read_file()
```
Reproject all data to a projected CRS (UTM) with
```
gdf.to_crs()
```
Define model extent with
```
gg.utils.set_extent()
```
or from GeoDataFrame bounds
Clip vector data to extent with
```
gg.vector.clip_by_extent()
```
Extract interface XYZ from contacts using
```
gg.vector.extract_xyz(gdf, dem)
```
Extract orientation XYZ from structural measurements
Convert strike to dip direction (azimuth = strike + 90)
Validate that all data shares the same CRS and falls within extent
Pass prepared DataFrames to GemPy model

使用
```
gpd.read_file()
```
加载地质图（接触带、地层）
使用
```
gdf.to_crs()
```
将所有数据重投影至投影CRS（UTM）
使用
```
gg.utils.set_extent()
```
或GeoDataFrame边界定义模型范围
使用
```
gg.vector.clip_by_extent()
```
将矢量数据按范围裁剪
使用
```
gg.vector.extract_xyz(gdf, dem)
```
从接触带中提取界面XYZ坐标
从构造测量数据中提取产状XYZ坐标
将走向转换为倾向方位角（方位角 = 走向 + 90）
验证所有数据使用相同CRS且位于范围内
将预处理好的DataFrame传入GemPy模型

Tips

小贴士

Always check CRS - All data must be in the same coordinate system
Use UTM for modelling - Meters are easier than degrees
Assign Z from DEM - Ensures consistent elevations across datasets
Validate geometry - Fix invalid geometries before processing
Buffer extent slightly - Avoid edge effects in interpolation

始终检查CRS - 所有数据必须使用相同的坐标系
建模使用UTM - 米制单位比角度单位更易用
从DEM获取Z值 - 确保数据集间高程一致
验证几何图形 - 处理前修复无效几何图形
适当扩大范围缓冲区 - 避免插值时出现边缘效应

References

参考资料

Data Extraction Methods - Extract interfaces, orientations, and profiles
Vector and Raster Operations - Detailed processing workflows

数据提取方法 - 提取界面、产状和剖面数据
矢量与栅格操作 - 详细处理工作流

Scripts

脚本

scripts/prepare_gempy_data.py - Prepare spatial data for GemPy model input

scripts/prepare_gempy_data.py - 为GemPy模型输入准备空间数据