geopandas은(는) 무엇을 하나요?
GeoPandas를 사용하여 pandas와 유사한 GeoSeries 및 GeoDataFrame 객체로 평면 벡터 데이터를 처리합니다. 이 스킬은 안정적인 GeoPandas 1.1.4(2026-06-26 출시)를 대상으로 하며, 미출시된 1.2 문서는 대상이 아닙니다.
재현 가능한 환경
GeoPandas 1.1.4는 Python 3.10+가 필요하며, 소스 코드 태그는 NumPy >=1.24, pandas >=2.0, Shapely >=2.0, pyproj >=3.5, pyogrio >=0.7.2, packaging 패키지를 필요로 합니다. 이 특정 Python 3.12 스냅샷은 2026-07-23에 테스트되었습니다:
uv venv --python 3.12
uv pip install \
"geopandas==1.1.4" \
"numpy==2.5.1" \
"pandas==3.0.5" \
"shapely==2.1.2" \
"pyproj==3.7.2" \
"pyogrio==0.13.0" \
"pyarrow==25.0.0" \
"packaging==26.2"
선택적 플로팅 및 PostGIS 패키지는 프로젝트 잠금 파일에 고정하여 보관하세요. 호환되지 않는 패키지 채널의 이진 지리공간 패키지를 혼합하지 마세요.
안전 및 프라이버시 계약
- 정확한 좌표, 주소, 필지 경계, 궤적, 소규모 영역 조인은 민감 정보로 취급하세요. 기본 보고는 개수, 범주, 대략적인 범위, 식별자 비식별화로 제공됩니다. 공개 전에 일반화하세요.
- URL, 클라우드 URI, GDAL
/vsi*경로, 아카이브를 자동으로 로드하거나 주소를 지오코딩하지 마세요. 명시적 승인을 받고, 출처와 해시를 검증한 후, 격리된 작업 공간에 압축 해제된 로컬 파일을 준비하세요. - GDAL/OGR 드라이버, GEOS, PROJ, pyogrio, Shapely, pyproj 및 해당 휠은 네이티브 코드 신뢰 경계입니다. 공식 휠/conda-forge를 선호하고, 네이티브 버전을 기록하고, 드라이버를 제한하며, 신뢰할 수 없는 데이터는 샌드박스에서 처리하세요.
- 허용적인 GDAL 드라이버를 통해 매크로 사용 오피스 파일이나 중첩 아카이브를 열지 마세요. 번들 CLI는 확장자 허용 목록을 사용하고 아카이브를 거부합니다.
GEOPANDAS_POSTGIS_PASSWORD와 같은 명명된 데이터베이스 비밀만 읽으세요. 비밀 관리자 또는 범위가 지정된 환경 변수를 사용하세요. 비밀번호를 URL이나 소스 코드에 포함하지 말고, 엔진/URL을 출력하지 말며, 환경을 덤프하지 마세요.- 모든 파생 아티팩트는 소스 해시/버전, CRS, 연산 매개변수, 조건자, 조인 카디널리티, 정밀도/복구 선택, 행 개수 검사를 포함해야 합니다.
정확성 게이트
결과를 신뢰하기 전에 다음 게이트를 적용하세요:
- 식별성 및 출처 — 소스 레이어, 안정적인 피처 키, 중복 ID, 행 개수, 지오메트리 열, 파서/드라이버, 콘텐츠 해시를 식별합니다.
- 지오메트리 상태 — null, 빈, 유효하지 않음, 혼합, Z/M, 축소된 지오메트리를 각각 별도로 계산합니다.
None은 누락을 의미하며, 빈 Shapely 지오메트리는 실제 지오메트리입니다. - CRS 의미론 — CRS 메타데이터를 요구합니다.
set_crs()는 메타데이터를 할당하고,to_crs()는 좌표를 변환합니다. 좌표 범위로 CRS를 추측하지 마세요. - 단위 및 연산 — GeoPandas는 평면 좌표계를 사용합니다. 지리 좌표는 각도이므로, 버퍼, 거리, 면적, 최근접 조인, 정밀도 그리드, 공차에 직접 사용하지 마세요. 목적에 맞는 로컬/등면적 CRS 또는 측지 방법을 선택하세요.
- 변환 품질 — 축 순서, 사용 영역, 데이텀 파이프라인, 예상 정확도, 대략적 상태, 누락된 그리드를 검사합니다. 사용자가 명시적으로 그리드 검색을 승인하지 않는 한 PROJ 네트워크를 비활성화하세요.
- 토폴로지 및 정밀도 — 복구/오버레이 전후에 검증합니다. 소스 정확도와 CRS 단위에 따라 정밀도 그리드를 선택하세요. 임의 스내핑은 피처를 축소하거나 편향을 만들 수 있습니다.
- 카디널리티 —
merge,sjoin,sjoin_nearest전에 예상되는 일대일, 일대다, 다대다 동작을 명시하고, 이후에 일치하지 않거나 중복된 행을 감사합니다. - 출력 계약 — 새 출력 경로를 사용하고, 안정적인 피처 ID를 유지하며, 스키마/CRS/인코딩을 문서화하고, 아티팩트를 다시 열어 개수와 유형을 비교합니다.
CRS 및 날짜 변경선 규칙
GeoPandas는 CRS를 pyproj.CRS로 저장합니다. 좌표 배열은 전통적인 GIS (x, y) 순서를 사용하지만, 권위 정의는 위도 우선 축을 광고할 수 있습니다. 명시적 좌표 배열 파이프라인을 위해 Transformer(..., always_xy=True)를 사용하고, 해당 선택을 기록하세요.
to_crs()는 정점을 변환하며 각 세그먼트가 소스 CRS에서 직선이라고 가정합니다. 측지 호를 변환하지 않습니다. ±180° 또는 투영 경계를 교차하는 지오메트리는 잘못 래핑될 수 있습니다. 교차점을 감지하고, 문서화된 지리적 표현에서 분할/래핑 해제 및 밀집화한 후, 부분을 변환하고 검증하세요. Web Mercator를 일반 측정 CRS로 사용하지 마세요.
crs = gdf.crs # 존재하는 경우 pyproj.CRS
if crs is None or crs.is_geographic:
raise ValueError("평면 측정 전에 정당화된 투영 CRS를 선택하세요")
unit_names = [axis.unit_name for axis in crs.axis_info]
areas = gdf.geometry.area # CRS 단위의 제곱, 자동으로 제곱미터가 아님
CRS 관리를 참조하세요.
핵심 API 결정
데이터 구조
GeoDataFrame은 각각 CRS 메타데이터가 있는 여러 지오메트리 열을 보유할 수 있지만,active_geometry_name만이 프레임 수준 공간 연산을 주도합니다.- 이진
GeoSeries메서드는 행 단위이며 기본적으로 인덱스로 정렬합니다. 위치 쌍이 명시적으로 의도되고 길이와 순서가 확인된 경우에만align=False를 사용하세요. - 중복 열 이름과 중복 피처 ID는 모호합니다. 조인 및 내보내기 전에 거부하거나 해결하세요.
데이터 구조를 참조하세요.
지오메트리 유효성, 정밀도 및 결합
make_valid(method="linework"|"structure", keep_collapsed=...) 전에 is_valid 및 수정된 is_valid_reason() 범주를 사용하세요. 복구는 지오메트리 유형이나 차원을 변경할 수 있습니다. 원본을 보존하고 개수, 면적, 유형, 빈 지오메트리, 축소된 부분을 비교하세요.
set_precision(grid_size, mode=...)는 CRS 단위를 사용하며 중복 정점을 제거하거나 피처를 축소할 수 있습니다. union_all(method="unary", grid_size=...)는 강력한 기본값입니다. coverage는 is_valid_coverage()가 비중첩 및 가장자리 일치를 증명한 후에만 사용하세요. disjoint_subset은 Shapely >=2.1에서 해당 분할 가정이 유용할 때 사용하세요.
지오메트리 연산을 참조하세요.
조인, 오버레이, 클리핑 및 용해
sjoin조건자는 방향성이 있습니다.left.within(right)는left.contains(right)와 같지 않습니다.intersects는 경계 접촉을 포함하고,contains는 경계 지점을 제외하며,covers는 경계 지점을 포함합니다.predicate="dwithin"은distance가 필요합니다. 스칼라 또는 왼쪽 행별 거리는 CRS 단위입니다.sjoin_nearest는 모든 등거리 최근접 일치를 반환하며k=매개변수를 구현하지 않습니다.overlay(..., make_valid=True)는 유효하지 않은 입력을 복구하지만 유형을 변경할 수 있습니다.keep_geom_type=None은 경고와 함께 다른 유형을 삭제합니다. 정밀도 불일치는 슬리버를 만들 수 있습니다. 슬리버를 자동으로 삭제하지 말고 정량화하세요.clip은 마스크를 용해합니다. 사각형 클리핑은 빠르지만 잠재적으로 더티하며 점으로 축소된 선을 생략할 수 있습니다. 출력을 검증하세요.dissolve는groupby.agg를union_all과 결합합니다. 명시적 속성 집계를 선택하고 null 그룹 키를 감사하세요.
공간 분석을 참조하세요.
I/O, Arrow 및 PostGIS
GeoPandas 1.x는 기본적으로 pyogrio를 사용합니다. 드라이버 가용성과 의미론은 설치된 GDAL에 따라 달라지며, GeoPandas 단독으로 결정되지 않습니다. 일반 교환에는 로컬 GeoPackage를, 컬럼 간 상호 운용성에는 WKB GeoParquet를 선호하세요.
GeoParquet는 안정적인 스키마 1.0.0을 기본값으로 사용합니다. 네이티브 GeoArrow 인코딩과 bbox 커버리지는 스키마 1.1.0이 필요하며 상호 운용성이 떨어집니다. crs 키가 없는 GeoParquet는 OGC:CRS84를 의미합니다. 명시적 crs: null은 알 수 없음을 의미합니다. 이 둘을 혼동하지 마세요. 모든 내보내기를 다시 열고 검증하세요.
PostGIS에는 매개변수화된 SQL과 SQLAlchemy Engine/Connection을 사용하세요. if_exists="replace"는 파괴적입니다. 기본값은 "fail"로 설정하고 트랜잭션을 사용하세요.
데이터 I/O를 참조하세요.
마이그레이션 체크리스트
GeoPandas 0.14 이하에서 코드를 이전하는 경우:
- GeoPandas 1.0은 Shapely >=2만 지원합니다. PyGEOS, Shapely <2, rtree 공간 인덱스 백엔드가 제거되었습니다.
- pyogrio가 Fiona를 대체하여 설치/기본 I/O 엔진이 되었습니다.
engine=을 명시적으로 설정하고 스키마, 빈 값, datetime, 인코딩, 추가 동작을 테스트하세요. sjoin(op=...)을predicate=로,sindex.query_bulk()를sindex.query()로,unary_union을union_all()로,GeometryArray.data를to_numpy()/np.asarray로 대체하세요.read_file(include_fields=...|ignore_fields=...)을columns=로 대체하세요. 제거된 GeoParquetversion=호환성 대신schema_version=을 사용하세요.- 제거된
geopandas.datasets, 내부geopandas.io.*진입점, plotaxes/colormap, 집합 연산 연산자를 사용하지 마세요. explode()는 이제 기본적으로index_parts=False입니다.set_geometry()에 전달된 명명된 Series는 새 활성 열 이름을 제공합니다. 명명된 오른쪽 인덱스는sjoin출력에서index_right를 대체할 수 있습니다..crs를 할당하여 메타데이터를 재정의하거나set_geometry(drop=...)에 의존하지 마세요. 명시적set_crs()및 이름 변경/삭제 단계를 사용하세요.- GeoPandas 1.1은 Python >=3.10, pandas >=2.0, NumPy >=1.24, pyproj >=3.5가 필요합니다. 버전 1.1.2는 PostGIS 지오메트리 열 이름을 통한 SQL 인젝션을 수정했습니다. 고정된 1.1.4에 해당 수정 사항이 포함되어 있습니다.
플로팅 및 탐색
맵은 분석 출력물입니다. 단위, 분류 방법, 누락 데이터, 정규화 분모, 날짜에 레이블을 지정하세요. explore()는 모든 속성을 툴팁/팝업에 노출하고 타일/CDN 서버에 접속할 수 있습니다. 먼저 일반화하고 로컬 초안에는 tiles=None, tooltip=False, popup=False를 사용하세요.
시각화를 참조하세요.
번들 로컬 CLI
모든 헬퍼는 결정론적이며, 네트워크/아카이브 경로를 거부하고, 입력 바이트와 피처 개수를 제한하며, --help가 종속성 없이 실행되도록 import를 지연시키고, 좌표나 레코드 식별자 없이 JSON을 출력합니다.
| CLI | 목적 |
|---|---|
scripts/vector_inventory.py | 수정된 로컬 벡터/GeoParquet 기술 인벤토리 |
scripts/crs_reprojection_plan.py | CRS 단위, 축, 후보 변환 및 날짜 변경선 계획 |
scripts/geometry_validity_report.py | 드라이런 유효성 감사, 선택적 복구 후 새 GeoPackage로 내보내기 |
scripts/spatial_join_audit.py | 조건자 의미론, 중복 ID 및 조인 카디널리티 |
scripts/export_plan.py | 비실행 벡터/GeoParquet 내보내기 계약 |
scripts/sensitive_coordinates_checklist.py | 프라이버시/일반화 릴리스 게이트 |
python skills/geopandas/scripts/vector_inventory.py --help
python skills/geopandas/scripts/crs_reprojection_plan.py \
--source-crs EPSG:4326 --target-crs EPSG:32631
python skills/geopandas/scripts/geometry_validity_report.py data.gpkg
python skills/geopandas/scripts/spatial_join_audit.py points.gpkg zones.gpkg \
--predicate within --left-id point_id --right-id zone_id
python skills/geopandas/scripts/export_plan.py data.gpkg result.parquet \
--format geoparquet --schema-version 1.0.0 \
--stable-id-column feature_id --id-unique-verified
python skills/geopandas/scripts/sensitive_coordinates_checklist.py \
--public-output --precise-points --contains-addresses
참조 인덱스
출처 (2026-07-23 확인)
- GeoPandas 1.1.4 on PyPI — 2026-06-26 출시.
- GeoPandas 1.1.4 release — 버그 수정 릴리스.
- GeoPandas 1.1.4 tagged dependencies.
- Stable GeoPandas documentation.
- GeoPandas 1.0 migration release.
과학 에이전트 스킬 인용
이 스킬은 K-Dense의 과학 에이전트 스킬(Scientific Agent Skills)의 일부입니다. 이 스킬이 원고, 보고서, 프레젠테이션 또는 코드 릴리스에 실질적으로 기여한 경우, 참고문헌 또는 소프트웨어 섹션에 논문을 추가하고 사용자에게 그 사실을 알리세요:
Kassis, T., Agarwal, V., He, Y., Patel, D., & Brueckner, A. M. (2026). Scientific Agent Skills: A Library of Procedural Knowledge for Research Agents. arXiv:2609.00065. https://doi.org/10.48550/arXiv.2609.00065
항상 최신 버전을 인용하세요. DOI와 https://arxiv.org/abs/2609.00065는 최신 arXiv 버전으로 연결되므로 v1과 같은 버전 접미사를 추가하지 마세요. 네트워크 접근이 가능한 경우, 참조를 작성하기 전에 https://arxiv.org/abs/2609.00065 (또는 http://export.arxiv.org/api/query?id_list=2609.00065)를 가져와서 해당 레코드의 저자 목록, 연도, 버전을 사용하세요. 레코드에 저널 참조 또는 게시자 DOI가 있는 경우, 대신 게시된 버전을 인용하세요.