# VWorld Land Information Tool (브이월드 토지정보 조회 플러그인)

## 개요

이 QGIS 플러그인은 브이월드(VWorld) API를 활용하여 토지 관련 정보를 종합적으로 조회하는 도구입니다. QGIS 맵 캔버스에서 선택한 폴리곤 영역을 기준으로 다양한 토지 정보를 조회하고, 대시보드 형태로 시각화하며, 보고서로 내보낼 수 있습니다.

## 주요 기능

### 1. 브이월드 API 연동
- **연속지적도 조회**: 선택한 영역 내 필지 정보 및 지오메트리 조회
- **토지임야정보 조회**: 토지 및 임야 구분 정보
- **토지특성정보 조회**: 지목, 등급, 도로접면, 지형지세, 이용상황
- **개별공시지가 조회**: 연도별 공시지가 정보
- **토지이용계획 조회**: 용도지역, 도시계획, 기타용도
- **토지소유자정보 조회**: 소유구분 및 필지 정보

### 2. 인터랙티브 대시보드
- 시도/시군구/지목별 필터링
- 실시간 통계 업데이트
- **지목별 파이 차트**: 필지 분포 시각화
- **공시지가 바 차트**: 가격대별 분포 시각화

### 3. 정밀 면적 분석
- **VWorld 연속지적도 API 지오메트리 활용**: 토지면적 조회
- **QGIS 좌표 변환**: Korea 2000 / Central Belt (EPSG:5186) 기준 정확한 면적 계산
- **편입면적 계산**: 선택 폴리곤과 필지 지오메트리 교차면적 계산

### 4. 트리 구조 결과 표시
- 조회 결과를 계층적으로 표시
- 각 필지별 상세 정보 확인

### 5. 보고서 내보내기
- 엑셀(CSV) 형식 내보내기
- HTML 보고서 형식 내보내기
- 대시보드 통계 포함

### 6. 구역계 설정/편집 (v1.5.0 NEW -  매뉴얼 이식)
- **필지선택**: 지도 클릭으로 필지 추가/삭제 (선택 영역 빨간 표시, VWorld POINT 질의)
- **영역그리기**: 폴리곤 직접 그리기(필지 모서리 스냅, 더블클릭/Enter 완료) + 영역삭제(차집합)
- **파일 업로드**: DXF / ZIP(SHP) / GeoJSON + 좌표계 선택 (DWG는 DXF 변환 후 사용)
- **주소 업로드**: CSV/XLSX 1열 주소 목록 → VWorld 주소검색으로 필지 일괄 등록 (최대 500건)
- **소재지 목록**: 필지별 면적/편입면적/편입상태 확인, 0.1m2 미만 부분편입 자동제외(해제 가능)
- **구역 확정**: '구역계' 메모리 레이어 생성 → 조회 조건 "구역계 사용"으로 폴리곤 정밀 조회
- **스타일 편집**: 선·면 색상/두께/투명도 + 위계 맨앞으로 + 버텍스편집(QGIS 꼭짓점 도구 연동)

### 7. 입지분석 (v1.5.0 NEW)
- **단면분석**: 단면선 최대 2개 그리기 → 거리-고도 프로파일 차트, 차트 호버 시 지도 위치 마커,
  차트 확대보기, 엑셀 내보내기 (OpenTopoData SRTM 30m)
- **개발가능지 분석**: 표고(기준 해발고도+표고차)·경사(급경사 기준) 격자 분석 + 환경등급(생태자연도/
  식생영급/국토환경성) 수동 입력 → 등급별 면적표 + 주제도 레이어. 법률 기준 초기값/초기화 제공
- **토지형상 분석**: 과소필지(용도지역별 기준면적)·부정형·세장형(최소외접직사각형 기반) 자동판정,
  판정 셀 클릭 토글 수정(과소→부정형·세장형→일반), 기준값 편집

### 8. 법률분석 (v1.5.0 NEW)
- **허용용도분석**: 건축물 용도(별표1 대분류 30종) × 대상지 용도지역 → 가능/조례위임/불가능 간이판정
  + 조건분석 수동 수정(가능/보류/불가/조례위임/지자체협의)
- **정비사업 요건검토**: 서울 4유형/지방 3유형 구역지정 요건(필수/선택) vs 현황 자동산출(구역면적·
  과소필지율 등) 비교, 현황 수치 수정 시 즉시 재판정
- **소규모정비사업**: 자율주택/가로주택/소규모재건축/소규모재개발 유형별 요건 충족 분석

### 9. 사업비분석 (v1.5.0 NEW)
- **토지이용계획**: 사업 유형별(도시개발 주거형/복합형, 산업단지) 평균 용지비율 면적표,
  비율 직접 편집 + 합계 100% 검증 + 초기화
- **추정사업비**: 기준년도 선택 시 건설공사비지수로 물가변동 자동 반영, 보상비/조성비/기반시설비/
  부대비/예비비 산출, 엑셀 내보내기 (참고용 추정치)

### 10. 레이어 관리 / 공통 기능 (v1.5.0 NEW)
- **일반레이어**: VWorld WMS 공간정보 카탈로그(용도지역·개발제한구역·행정경계 등 17종) 켜기/끄기,
  키워드 검색, 전체 선택 해제, 임의 레이어ID 직접 추가
- **사용자레이어**: 위계 맨앞으로 / 구역계로 이동 / 범례편집(구간수·컬러램프·구간값) /
  속성보기(+엑셀 xlsx 내보내기) / DXF 내보내기(도형만) / SHP 내보내기(도형+속성)
- **SHP 일괄 내보내기**: 조회 데이터 전체를 EPSG:5174(기본)/5186/4326으로 일괄 저장,
  구역 주변 1km 지적 포함 옵션
- **지도 캡처**: 현재 지도화면 PNG 저장

### 11. 개발성 분석 (v1.6.0 NEW - 동종 QGIS 플러그인 벤치마킹)
국내외 동종 토지·도시계획 분석 QGIS 플러그인(MORPHINT·PlanX·Cadastral Divisions·
Split Polygon·road/accessibility 계열)을 조사·분석하여 기존에 없던 기능을 추가했다.
(상세: 루트 `신기능_명세서.md`)
- **개발용량 분석**: 용도지역별 법정 건폐율·용적률 상한으로 필지·구역의 건축면적·허용연면적·
  추정층수·공지율(OSR) 산출. 기준값 직접 수정(조례 강화 반영), 면적가중 평균/총 개발규모 집계,
  용적률 구간 주제도, 엑셀 내보내기 (MORPHINT BCR/FAR/OSR · PlanX Spacematrix 참조)
- **접도·맹지 분석**: 도로 레이어 대비 필지별 접도여부·접도길이·최단 도로거리 산출 →
  맹지/준맹지/건축가능(건축법 제44조 2m 접도) 판정, 판정별 주제도, 엑셀 내보내기
- **필지 분할 시뮬레이션**: 구역/필지를 N등분(등면적)·목표면적별·분할선으로 분할,
  과소필지 기준 미달 조각 경고, 분할 결과 메모리 레이어·면적표·엑셀 (Cadastral Divisions/Split Polygon 참조)

## 요구사항

- QGIS 3.36 이상
- 브이월드 API 인증키 (https://www.vworld.kr 에서 발급)
- Python 3.x (QGIS 내장)
- PyQt5 (QGIS 내장)

## 설치 방법

### ZIP 파일로 설치

1. `qgis_vworld_land_info` 폴더를 ZIP 파일로 압축합니다.
2. QGIS를 실행합니다.
3. 메뉴에서 `플러그인` > `플러그인 관리 및 설치` 선택
4. `ZIP에서 설치` 탭 선택
5. 압축한 ZIP 파일 선택 후 `플러그인 설치` 클릭

### 수동 설치

1. `qgis_vworld_land_info` 폴더를 QGIS 플러그인 디렉토리로 복사합니다.
   - Windows: `C:\Users\{사용자명}\AppData\Roaming\QGIS\QGIS3\profiles\default\python\plugins\`
   - Linux: `~/.local/share/QGIS/QGIS3/profiles/default/python/plugins/`
   - macOS: `~/Library/Application Support/QGIS/QGIS3/profiles/default/python/plugins/`

2. QGIS 재시작 후 플러그인을 활성화합니다.

## 사용 방법

### 1. API 키 설정
1. 브이월드 포털(https://www.vworld.kr)에서 API 키를 발급받습니다.
2. 플러그인 실행 후 API 키를 입력합니다.

### 2. 폴리곤 선택
1. 폴리곤 레이어를 QGIS에 로드합니다.
2. 조회할 폴리곤을 선택합니다.
3. 플러그인에서 레이어를 선택합니다.

### 3. 조회 실행
1. "조회 시작" 버튼을 클릭합니다.
2. 진행률 표시바에서 진행 상황을 확인합니다.
3. 조회 완료 후 결과를 확인합니다.

### 4. 결과 분석
- **트리 구조**: 왼쪽 패널에서 계층적 결과 확인
- **대시보드**: 통계 요약, 필터링, **차트 시각화**
- **탭별 상세정보**: 각 데이터 유형별 상세 테이블

### 5. 보고서 내보내기
- "엑셀 내보내기": CSV 형식으로 저장
- "보고서 내보내기": HTML 형식으로 저장

### 6. 구역계 워크플로 (v1.5.0 - 레이어 선택 없이 지도에서 직접)
1. '구역계' 탭에서 [필지추가]/[영역추가] 또는 파일/주소 업로드로 분석영역 생성
   (도구 사용 중에는 다이얼로그가 숨겨지고 캔버스 우상단 미니바의 [완료]/[취소]로 제어)
2. [적용 (소재지 목록 갱신)] → 필지별 편입면적·편입상태 확인, 제외 체크 조정
3. [구역 확정] → '구역계' 레이어 생성 + 조회 조건의 "구역계 사용" 자동 체크
4. [조회 시작] → 구역계 폴리곤 기준으로 전체 토지정보 조회
5. 입지분석(단면/개발가능지/토지형상) · 법률분석 · 사업비분석 탭에서 후속 분석

※ 단면분석의 단면선 그리기도 동일하게 지도에서 직접 그립니다 (더블클릭/Enter 완료).

## 파일 구조

```
qgis_vworld_land_info/
├── __init__.py                # 플러그인 초기화
├── main.py                    # 메인 로직 및 GUI (탭 구성/조회 오케스트레이션)
├── api_manager.py             # VWorld Data/Search/NED API (POINT·POLYGON geomFilter 포함)
├── constants.py               # 지목 코드 매핑
├── legal_standards.py         # 법정 기준 데이터 (허용용도 매트릭스·정비요건·단가 등)
├── map_tools.py               # 맵 도구 (필지클릭/폴리곤·라인 그리기)
├── district_manager.py        # 구역계 설정/편집 + 소재지 목록 + 구역계 레이어
├── layer_manager.py           # WMS 일반레이어/사용자레이어/범례편집/내보내기/지도캡처
├── dashboard_widget.py        # 대시보드 (필터/통계/차트)
├── land_info_tab.py           # 데이터 타입별 테이블 탭
├── chart_widget.py            # 파이/바/라인 차트 (QPainter)
├── terrain_analyzer.py        # 지형분석 (고도/경사도 등급)
├── section_analyzer.py        # 단면분석 (고도 프로파일)
├── feasibility_analyzer.py    # 개발가능지 분석
├── parcel_shape_analyzer.py   # 토지형상 (과소/부정형·세장형)
├── permitted_use_analyzer.py  # 허용용도분석
├── redevelopment_analyzer.py  # 정비사업/소규모정비 요건검토
├── project_cost_analyzer.py   # 사업비분석 (토지이용계획/추정사업비)
├── cost_calculator.py         # 기반비용 (부담금 추정)
├── streetview_manager.py      # 가로경관 사진 수집
├── ai_analyzer.py             # AI 분석 (OpenAI/Anthropic)
├── export_manager.py          # CSV/HTML/DOCX/xlsx 내보내기
├── metadata.txt               # 플러그인 메타데이터
├── icon.png                   # 툴바 아이콘
└── README.md                  # 사용 설명서
```

※ 전체 기능 명세( 매뉴얼 29페이지 분석·구현범위)는 저장소 루트의 `기능명세서.md` 참조.

## 브이월드 API 참조

- 브이월드 2D API: https://www.vworld.kr/dev/v4dv_opn2dmap2guide_s001.do
- 연속지적도 API: https://www.vworld.kr/dev/v4dv_2ddataguide2_s002.do?svcIde=cadastral
- 토지임야정보: https://www.vworld.kr/dtna/dtna_apiSvcView_s001.do?dataSetSeq=29
- 토지특성정보: https://www.vworld.kr/dtna/dtna_apiSvcView_s001.do?dataSetSeq=4
- 개별공시지가: https://www.vworld.kr/dtna/dtna_apiSvcView_s001.do?dataSetSeq=6
- 토지이용계획: https://www.vworld.kr/dtna/dtna_apiSvcView_s001.do?dataSetSeq=14
- 토지소유자정보: https://www.vworld.kr/dtna/dtna_apiSvcFc_s001.do

## 문제 해결

### API 키 오류
- 브이월드 포털에서 API 키가 정상적으로 발급되었는지 확인
- 도메인 설정이 올바른지 확인

### 조회 결과 없음
- 선택한 폴리곤이 대한민국 영역 내에 있는지 확인
- 좌표계가 올바르게 설정되어 있는지 확인

### 네트워크 오류
- 인터넷 연결 상태 확인
- 방화벽 설정 확인

## 라이선스

MIT License

## 연락처

- 이슈 리포트: https://github.com/example/qgis_vworld_land_info/issues
- 이메일: developer@example.com

## 버전 이력

### v1.6.1 (2026-06-29)
- **플러그인 저장소 업로드 대응**: plugins.qgis.org 패키지 검증 통과를 위한 보완
  - 패키지 루트에 `LICENSE`(MIT) 파일 추가 — 저장소 필수 요건
  - Bandit 보안 스캔 B310(`urllib.request.urlopen` 스킴 경고) 6건 해소:
    `ai_analyzer.py`·`api_manager.py`·`streetview_manager.py`·`terrain_analyzer.py`의
    모든 네트워크 호출에 http/https 스킴 검증 가드 추가 + 고정 신뢰 엔드포인트에 대한 `# nosec B310` 명시
  - 기능 변경 없음(패키징·보안 정비). MEDIUM 이상 잔여 보안 이슈 0건

### v1.6.0 (2026-06-13)
- **개발성 분석 탭 신설 (동종 QGIS 플러그인 벤치마킹)**: 국내외 토지·도시계획 분석 플러그인을
  웹에서 조사·분석하여 기존 `기능명세서.md`에 없던 3개 신기능을 추가 (상세: 루트 `신기능_명세서.md`)
  - **개발용량 분석**(`capacity_analyzer.py`): 용도지역별 법정 건폐율·용적률 상한 → 건축면적·
    허용연면적·추정층수·공지율 산출, 기준 직접수정, 구역 집계, 용적률 주제도, 엑셀
  - **접도·맹지 분석**(`road_access_analyzer.py`): 도로 레이어 대비 접도여부·접도길이·최단거리 →
    맹지/준맹지/건축가능 판정(건축법 제44조), 판정별 주제도, 엑셀
  - **필지 분할 시뮬레이션**(`parcel_split_analyzer.py`): N등분/목표면적/분할선 분할,
    과소필지 경고, 결과 레이어·면적표·엑셀
- 법정 기준 `legal_standards.py`에 `BCR_FAR_BY_ZONE`(용도지역 21종 건폐율/용적률 상한)·
  `match_capacity_zone()` 추가, 자가검사 확장. 각 신규 탭은 `set_land_info`/`reset`/
  `get_report_data` 공통 인터페이스 구현(보고서 자동 포함).

### v1.5.1 (2026-06-12)
- **보고서 전체 탭 포함**: [보고서 내보내기](HTML/DOCX)와 [엑셀 내보내기](CSV) 실행 시
  기존 데이터 탭(대시보드/연속지적도/토지이용계획 등)에 더해 **전체 분석 탭의 내용이
  모두 보고서에 포함**되도록 개선 — 구역계(소재지 목록·확정 면적), 지형분석(표고/경사
  등급/노후도), 가로경관(촬영 정보 + 사진 삽입), 기반비용(부담금 요약·필지별 상세),
  단면분석(프로파일 표), 개발가능지(기준·등급별 면적), 토지형상(판정 목록·수동수정 반영),
  허용용도분석(용도지역별 판정), 정비사업·소규모정비(요건표·종합판정),
  사업비분석(토지이용계획표·추정사업비 내역), AI 분석(분석 전문)
- 구현: 각 탭에 `get_report_data()` 공통 인터페이스 추가,
  `ExportManager`에 섹션 렌더러(CSV/DOCX/HTML) 신설 — 분석을 실행한 탭만 포함됨

### v1.5.0 (2026-06-11)
상용 토지분석 서비스 의 사용자 매뉴얼(10개 섹션 / 29개 페이지) 전체를 분석해 기능명세서
(`기능명세서.md`)를 작성하고, QGIS 3.36에서 구현 가능한 기능을 이식:
- **구역계 탭(NEW)**: 필지선택(클릭 추가/삭제·빨간 표시)·영역그리기(스냅)·영역삭제·
  파일 업로드(DXF/ZIP-SHP/GeoJSON+좌표계 선택)·주소 업로드(CSV/XLSX→PNU 변환)·
  소재지 목록(편입면적·0.1m2 미만 부분편입 자동제외)·구역 확정(메모리 레이어)·
  스타일 편집·버텍스편집·"구역계 사용" 조회(POLYGON 정밀 geomFilter)
- **입지분석 탭(NEW)**: 단면분석(단면선 2개·차트 호버 지도연동·확대보기·엑셀),
  개발가능지 분석(표고·경사 격자 + 환경등급 수동입력, 법정 초기값/초기화, 주제도 레이어),
  토지형상 분석(과소/부정형·세장형 자동판정 + 클릭 토글 결과수정 + 기준 편집)
- **법률분석 탭(NEW)**: 허용용도분석(용도지역 12종×건축물 용도 30종 간이 매트릭스 +
  조건분석 수동수정), 정비사업 요건검토(서울 4유형/지방 3유형, 현황 수정 즉시 재판정),
  소규모정비사업 요건검토(4개 유형)
- **사업비분석 탭(NEW)**: 토지이용계획(용지비율 프리셋·편집·100% 검증·초기화),
  추정사업비(기준년도 건설공사비지수 물가반영·엑셀 내보내기)
- **레이어 탭(NEW)**: VWorld WMS 일반레이어 카탈로그(검색·전체 해제·임의 ID 추가),
  사용자레이어(위계 맨앞으로/구역계로 이동/범례편집/속성보기+xlsx/DXF/SHP 내보내기),
  SHP 일괄 내보내기(EPSG:5174 기본·주변 1km 포함), 지도 캡처(PNG)
- **공통**: `legal_standards.py` 법정 기준 데이터 모듈(자가검사 내장), `export_table_xlsx`
  (openpyxl, 미설치 시 CSV 폴백), 라인 차트+호버(`chart_widget`), api_manager에
  POINT/POLYGON geomFilter·주소검색 추가 및 중복 DATA_TYPES 정리, 맵툴 수명주기 관리
  (다이얼로그 숨김+미니바, closeEvent/unload 정리)
- **구현 제외(기능명세서에 사유 기재)**: 작도(QGIS 기본 주석/스크래치 레이어와 중복),
  공적장부 발급(정부 인증·유료 회원제), DWG 업로드(OGR 미지원→DXF 변환 안내),
  OZ Report 출력(기존 HTML/DOCX 내보내기로 대체)

### v1.4.0 (2026-06-03)
브이월드 공장인허가 사전진단 서비스(PSS, pss.vworld.kr) 기능 분석을 바탕으로 QGIS 3.36.2에서 구현 가능한 기능 추가:
- **기반비용 산출 탭(NEW)**: 농지보전부담금·대체산림자원조성비·개발부담금(간이) 추정. 편입면적·지목·개별공시지가 기반, 단가 조정 가능. (참고용 추정치)
- **경사도 등급 분석(NEW)**: 지형분석 탭에 PSS 기준 3등급(20°미만/20~49°/50°이상) 분포·면적·비율 표시. 구조화 격자 셀별 경사도 산출.
- **필지 주변정보 버퍼(NEW)**: 선택 영역 기준 반경(1/3/5km) 버퍼를 EPSG:5186 메모리 레이어로 생성해 지도에 추가.

### v2.0.0 (2026-01-29)
- 개선된 면적 계산: VWorld 연속지적도 지오메트리 활용
- 편입면적 계산: 선택 폴리곤과 필지의 교차면적 정밀 계산
- 대시보드 차트 추가: 지목별 파이 차트, 공시지가 바 차트
- 토지소유자정보 탭 추가
- EPSG:5186 좌표계 변환을 통한 정확한 면적 계산

### v1.0.0 (2024-01-01)
- 최초 릴리스
- 브이월드 API 연동 기능
- 대시보드 및 필터링 기능
- 엑셀/HTML 내보내기 기능
