🌤️ 기상청 3차원 객관분석 기상 데이터 추출 및 바람 벡터 검증 시스템

KMA 3D Objective Analysis Grid Data Extraction & Wind Vector Verification System

본 프로젝트는 기상청(KMA)의 수치 객관분석 시스템(NetCDF 격자 자료)과 지상 기상 실측 API 데이터를 유기적으로 연계하여, 특정 타겟 위·경도에 대해 정밀한 5분 간격 기상 데이터를 추출하고 바람 벡터 데이터(U, V 성분)의 일관성 및 정합성을 수학적·과학적으로 검증 및 시각화하는 시스템입니다.

---

📂 디렉토리 구조 및 파일 역할

weather-api/
│
├── .gitignore                      # Git 저장소 등록 제외 패턴 설정 (venv, .env, *.csv, *.png)
├── .env.example                    # API 인증키 환경변수 설정 예시 파일
├── requirements.txt                # 프로젝트 실행에 필요한 의존성 라이브러리 목록
│
├── PROJECT_INFO.md                 # 프로젝트의 핵심 가치, 연구 배경 및 주요 결론 요약
├── README.md                       # 본 파일 (전체 상세 사용 가이드)
│
# [1] 데이터 추출 및 API 연동 스크립트
├── extract_weather_data.py          # 특정 관심 시점(visible-times.txt)의 전후 기상 데이터 단일 추출
├── extract_continuous_data.py       # 장기(4월 1일 ~ 5월 7일) 5분 연속 데이터 순차 추출 (싱글 스레드)
├── extract_continuous_data_fast.py  # ThreadPoolExecutor(스레드 5개) 기반 고속 연속 데이터 추출 및 정렬 병합
├── check_api_columns.py             # KMA API 컬럼 헤더 정보 디버깅 및 확인
│
# [2] 격자 분석 및 좌표 매핑
├── verify_grid.py                   # sfc_grid_latlon.nc(NetCDF) 격자망 로드 후 최인접 3x3 실제 격자 좌표 탐색
├── visualize_grid.py                # 가상 500m 기상 격자점 좌표 공간 시각화 및 검증
│
# [3] 바람 벡터 정합성 분석 및 검증
├── verify_wind_vectors.py           # 풍향/풍속 & U/V 성분 기상 삼각 공식 역산 및 기본 검증
├── analyze_relative_error.py        # 동서(U), 남북(V) 성분별 절대/상대/벡터 총합 오차율 정량화 분석
├── analyze_ws_error.py              # U, V 성분을 활용한 바람 크기(Wind Speed) 역산 및 오차 검증
│
# [4] 데이터 시각화
├── plot_weather_data.py             # 2중 축(기온·이슬점 vs 풍속) 시계열 그래프 생성 및 특정 타임스탬프 실선 표기
├── plot_weather_no_wind.py          # 풍속 제외 기온 및 이슬점 시계열 분석 차트 생성
├── plot_weather_with_humidity.py    # 기온, 이슬점 온도와 상대습도 변화를 다중 차트로 시각화
│
# [5] 원천 데이터 및 메타데이터 (설정)
├── sfc_grid_latlon.nc               # 기상청 3차원 객관분석 500m 해상도 격자 위/경도 원천 파일
├── weather_data_definition.csv      # 수집되는 10개 기상 관측 변수의 의미 및 단위 정의서 (핵심 메타데이터)
├── visible-times.txt                # 시각화 그래프 상에 하이라이트할 핵심 관측 시점 목록
└── target-coord.txt                 # 분석 타겟 중심 좌표

---

📊 기상 관측 변수 상세 정의 (Weather Data Columns)

본 시스템에서 추출 및 정제하여 처리하는 기상 변수는 weather_data_definition.csv에 정의되어 있으며 다음과 같습니다:

컬럼명 (Column)	설명 (Description)	단위 (Unit)	비고 (Remark)
tm	관측시각 (KST)	YYYYMMDDHHMI	한국 표준시 기준
ta	기온	°C	지상 1.5m 높이
hm	상대습도	%	-
td	이슬점 온도	°C	-
wd_10m	10분 평균 풍향	deg	0~360도 (북:0, 동:90, 남:180, 서:270)
ws_10m	10분 평균 풍속	m/s	-
uu	동서 바람 성분 (U)	m/s	서풍(+), 동풍(-)
vv	남북 바람 성분 (V)	m/s	남풍(+), 북풍(-)
rn_ox	강수 유무	-	0: 무강수, 1: 강수
vs	시정	km	가시거리

---

⚙️ 설치 및 개발 환경 구축 (Setup & Installation)

본 프로젝트는 Python 3.8 이상 환경에서 정상 동작합니다.

1. 가상환경 구축 및 의존성 라이브러리 설치

# 프로젝트 디렉토리로 이동
cd weather-api

# 가상환경 생성 (venv)
python3 -m venv venv

# 가상환경 활성화
# Windows (cmd): venv\Scripts\activate.bat
# Windows (PowerShell): .\venv\Scripts\Activate.ps1
# Linux / macOS:
source venv/bin/activate

# 의존성 패키지 설치
pip install --upgrade pip
pip install -r requirements.txt

2. KMA API 인증키 설정 (.env)

기상청 API 허브(APIS) 연동을 위해 인증키 설정이 필요합니다. 프로젝트 루트 디렉토리에 .env 파일을 생성하고 발급받은 인증키를 입력합니다:

# .env 파일 생성 및 편집
echo "KMA_API_KEY=발급받은_기상청_인증키" > .env

⚠️ 보안 경고 (CWE-798 방지): .env 파일은 인증키를 안전하게 로컬 환경에 보관하기 위한 파일입니다. 절대로 이 파일을 Git 원격 저장소에 커밋/업로드하지 마십시오. .gitignore 설정에 의해 자동 차단되지만, 항상 주의가 필요합니다.

---

🚀 파이프라인 실행 가이드 (Usage Pipeline)

데이터 분석과 정밀 격자 정합성 검증을 완벽하게 재현하기 위해 다음 순서로 스크립트를 실행해 주십시오.

Step 1. 최인접 실제 기상 격자 매핑

로컬의 NetCDF 격자망 파일(sfc_grid_latlon.nc)을 분석하여 타겟 위·경도와 매핑되는 기상청 격자의 인덱스(ny, nx) 및 인접 3x3 격자점 좌표를 확보합니다.

python verify_grid.py

• 출력 결과: 최인접 격자 좌표가 exact_grid_points.txt로 저장됩니다.

Step 2. 격자 시각화 검증

격자망 공간을 가시화하여 올바른 격자점이 설정되었는지 플롯을 생성해 확인합니다.

python visualize_grid.py

• 출력 결과: grid_points_visualization.png 생성 (중앙 좌표 빨간색 매핑)

Step 3. 5분 연속 데이터 고속 추출

스레드 풀 기반 병렬 처리를 통해 4월 1일부터 5월 7일까지의 기상 연속 데이터를 수집합니다.

python extract_continuous_data_fast.py

• 출력 결과: 대용량 통합 기상 데이터 파일 weather_data_continuous_20260401_20260507.csv 생성

Step 4. 바람 벡터 정합성 분석 및 오차 규명

수집된 기상 실측 데이터의 풍향/풍속 정보와 U/V 성분 정보의 물리적/수학적 정합성을 정량 검증합니다.

# 1. 기본적인 U/V 벡터 공식 역산 및 차이 확인
python verify_wind_vectors.py

# 2. 성분별 절대, 상대오차 및 벡터 총합 오차 종합 분석
python analyze_relative_error.py

# 3. U/V 기반 풍속 역산 정밀도 분석
python analyze_ws_error.py

• 주요 결론: 평균 절대 오차가 0.05 m/s 미만으로 산출되어, 소수점 처리 과정의 절사 오차를 제외하면 완벽하게 수학적 일관성을 가짐을 확인할 수 있습니다.

Step 5. 기상 변화 다중 차트 시각화

추출된 데이터로부터 온도, 이슬점, 풍속 등의 시계열 추이 분석 그래프를 생성합니다. visible-times.txt에 정의된 핵심 타겟 시점들이 붉은색 수직 실선으로 매핑됩니다.

python plot_weather_data.py

• 출력 결과: weather_timeseries_plot.png 이미지 생성

---

🧮 바람 벡터 역산 공식 (Scientific Formulas)

기상학적 바람 벡터 구성 공식은 다음과 같으며, verify_wind_vectors.py 등에 탑재되어 실증 검증을 수행합니다.

• 바람 벡터 성분 분해 (Decomposition) 바람이 불어오는 방향(풍향 \theta)과 강도(풍속 WS)로부터 불어나가는 벡터 $U$(동서성분)와 $V$(남북성분)를 구합니다:

  U = -WS \cdot \sin\left(\frac{\theta \cdot \pi}{180}\right)

  V = -WS \cdot \cos\left(\frac{\theta \cdot \pi}{180}\right)

• 바람 벡터 합성 (Reconstruction)

  WS_{calc} = \sqrt{U^2 + V^2}

• 오차 평가 지표 (Vector Relative Error)

  Error_{mag} = \sqrt{(U_{calc} - U_{obs})^2 + (V_{calc} - V_{obs})^2}

  Error_{rel} = \frac{Error_{mag}}{WS_{obs}}