Back to Details

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')
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')
interfaces = gg.vector.extract_xyz(gdf=gdf, dem='dem.tif')

Define model extent

定义模型范围

extent = [x_min, x_max, y_min, y_max]
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

核心模块

ModulePurpose
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 )
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

支持的格式

FormatExtensionReadWrite
Shapefile.shpYesYes
GeoJSON.geojsonYesYes
GeoPackage.gpkgYesYes
GeoTIFF.tifYesYes
ASCII Grid.ascYesYes
格式扩展名读取写入
Shapefile.shp是是
GeoJSON.geojson是是
GeoPackage.gpkg是是
GeoTIFF.tif是是
ASCII Grid.asc是是

Common CRS

常用CRS

EPSGDescription
4326WGS84 (lat/lon)
32632UTM Zone 32N
32633UTM Zone 33N
EPSG描述
4326WGS84（经纬度）
32632UTM 32N带
32633UTM 33N带

When to Use vs Alternatives

适用场景与替代方案对比

ScenarioRecommendation
Prepare GIS data for GemPy modellingGemGIS - purpose-built bridge between GIS and GemPy
General geospatial analysis in Pythongeopandas + rasterio - more flexible, larger community
GUI-based geological map processingQGIS - visual, interactive, plugin ecosystem
Extract XYZ + elevation from shapefiles and DEMsGemGIS - one-liner with 
extract_xyz()
Complex raster analysis pipelinesrasterio + 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

小贴士

  1. Always check CRS - All data must be in the same coordinate system
  2. Use UTM for modelling - Meters are easier than degrees
  3. Assign Z from DEM - Ensures consistent elevations across datasets
  4. Validate geometry - Fix invalid geometries before processing
  5. Buffer extent slightly - Avoid edge effects in interpolation
  1. 始终检查CRS - 所有数据必须使用相同的坐标系
  2. 建模使用UTM - 米制单位比角度单位更易用
  3. 从DEM获取Z值 - 确保数据集间高程一致
  4. 验证几何图形 - 处理前修复无效几何图形
  5. 适当扩大范围缓冲区 - 避免插值时出现边缘效应

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模型输入准备空间数据