# 🌤️ 기상청 3차원 객관분석 기상 데이터 추출 및 바람 벡터 검증 시스템
> **KMA 3D Objective Analysis Grid Data Extraction & Wind Vector Verification System**

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

---

## 📂 디렉토리 구조 및 파일 역할
```text
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. 가상환경 구축 및 의존성 라이브러리 설치
```bash
# 프로젝트 디렉토리로 이동
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` 파일을 생성하고 발급받은 인증키를 입력합니다:
```bash
# .env 파일 생성 및 편집
echo "KMA_API_KEY=발급받은_기상청_인증키" > .env
```
> ⚠️ **보안 경고 (CWE-798 방지)**: `.env` 파일은 인증키를 안전하게 로컬 환경에 보관하기 위한 파일입니다. **절대로 이 파일을 Git 원격 저장소에 커밋/업로드하지 마십시오.** `.gitignore` 설정에 의해 자동 차단되지만, 항상 주의가 필요합니다.

---

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

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

### Step 1. 최인접 실제 기상 격자 매핑
로컬의 NetCDF 격자망 파일(`sfc_grid_latlon.nc`)을 분석하여 타겟 위·경도와 매핑되는 기상청 격자의 인덱스(`ny`, `nx`) 및 인접 3x3 격자점 좌표를 확보합니다.
```bash
python verify_grid.py
```
- **출력 결과**: 최인접 격자 좌표가 `exact_grid_points.txt`로 저장됩니다.

### Step 2. 격자 시각화 검증
격자망 공간을 가시화하여 올바른 격자점이 설정되었는지 플롯을 생성해 확인합니다.
```bash
python visualize_grid.py
```
- **출력 결과**: `grid_points_visualization.png` 생성 (중앙 좌표 빨간색 매핑)

### Step 3. 5분 연속 데이터 고속 추출
스레드 풀 기반 병렬 처리를 통해 4월 1일부터 5월 7일까지의 기상 연속 데이터를 수집합니다.
```bash
python extract_continuous_data_fast.py
```
- **출력 결과**: 대용량 통합 기상 데이터 파일 `weather_data_continuous_20260401_20260507.csv` 생성

### Step 4. 바람 벡터 정합성 분석 및 오차 규명
수집된 기상 실측 데이터의 풍향/풍속 정보와 U/V 성분 정보의 물리적/수학적 정합성을 정량 검증합니다.
```bash
# 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`에 정의된 핵심 타겟 시점들이 붉은색 수직 실선으로 매핑됩니다.
```bash
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}}$$