npm package: @nullcode_realman/dji_kmz_parser
Description: convert kmz to json and json to kmz
Author: nullcodeRealman
Latest version: 0.0.3

# DJI KMZ Parser

DJI 드론의 KMZ 파일을 JSON으로 변환하고, JSON을 KMZ 파일로 생성할 수 있는 TypeScript 라이브러리입니다.

## ✨ 주요 기능

- 🔄 **KMZ ↔ JSON 변환**: DJI KMZ 파일과 JSON 간의 양방향 변환
- 📝 **완벽한 타입 지원**: TypeScript로 작성되어 타입 안전성 보장
- 🎯 **DJI 호환성**: DJI Pilot, DJI Flighthub 2와 완전 호환
- 🗜️ **최적화된 압축**: DJI와 동일한 압축률로 파일 크기 최적화
- 🌏 **한국어 문서화**: 모든 주석과 타입 정의가 한국어로 번역됨

## 📦 설치

```bash
# npm 사용
npm i @nullcode_realman/dji_kmz_parser
```

## 🚀 사용법

### 1. KMZ 파일을 JSON으로 변환

```typescript
import { kmzToJson } from '@nullcode_realman/dji_kmz_parser'

// 파일 업로드로 KMZ 파일 받기
const handleFileUpload = async (file: File) => {
  try {
    const response = new Response(file)
    const jsonData = await kmzToJson(response)
    console.log('변환된 JSON 데이터:', jsonData)
  } catch (error) {
    console.error('변환 오류:', error)
  }
}

// 또는 fetch로 KMZ 파일 가져오기
const loadKmzFile = async () => {
  try {
    const response = await fetch('/path/to/flight.kmz')
    const jsonData = await kmzToJson(response)
    console.log('변환된 JSON 데이터:', jsonData)
  } catch (error) {
    console.error('변환 오류:', error)
  }
}
```

### 2. JSON을 KMZ 파일로 변환

```typescript
import { jsonToKmz } from '@nullcode_realman/dji_kmz_parser'

// 샘플 JSON 데이터 (실제 사용 시에는 적절한 데이터 구조 사용)
const flightData = {
  template: {
    author: "사용자명",
    createTime: "1757489712000",
    updateTime: "1757489712000",
    missionConfig: {
      flyToWaylineMode: "safely",
      finishAction: "goHome",
      // ... 기타 설정
    },
    Folder: {
      templateType: "waypoint",
      autoFlightSpeed: "10.0",
      // ... 기타 설정
    }
  },
  waylines: {
    missionConfig: {
      // ... 미션 설정
    },
    Folder: {
      templateId: "0",
      waylineId: "0",
      // ... 항로 설정
    }
  }
}

const generateKmzFile = async () => {
  try {
    const kmzBlob = await jsonToKmz(flightData)
    
    // 파일 다운로드
    const url = window.URL.createObjectURL(kmzBlob)
    const a = document.createElement('a')
    a.href = url
    a.download = `flight-${new Date().getTime()}.kmz`
    a.click()
    
    // 메모리 정리
    window.URL.revokeObjectURL(url)
    
    console.log('KMZ 파일 생성 완료!')
  } catch (error) {
    console.error('KMZ 생성 오류:', error)
  }
}
```

### 3. Vue.js에서 사용하기

```vue
<template>
  <div>
    <input type="file" @change="handleKmzUpload" accept=".kmz" />
    <button @click="generateSampleKmz">샘플 KMZ 생성</button>
    
    <div v-if="kmzData">
      <h3>변환된 데이터:</h3>
      <pre>{{ JSON.stringify(kmzData, null, 2) }}</pre>
    </div>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { kmzToJson, jsonToKmz } from '@nullcode_realman/dji_kmz_parser'

const kmzData = ref(null)

const handleKmzUpload = async (event: Event) => {
  const file = (event.target as HTMLInputElement).files?.[0]
  if (!file) return
  
  try {
    const response = new Response(file)
    kmzData.value = await kmzToJson(response)
  } catch (error) {
    console.error('KMZ 변환 오류:', error)
  }
}

const generateSampleKmz = async () => {
  // 샘플 데이터로 KMZ 생성
  const sampleData = {
    template: { /* 템플릿 데이터 */ },
    waylines: { /* 항로 데이터 */ }
  }
  
  try {
    const kmzBlob = await jsonToKmz(sampleData)
    // 다운로드 로직...
  } catch (error) {
    console.error('KMZ 생성 오류:', error)
  }
}
</script>
```

### 4. React에서 사용하기

```tsx
import React, { useState } from 'react'
import { kmzToJson, jsonToKmz } from '@nullcode_realman/dji_kmz_parser'

const KmzConverter: React.FC = () => {
  const [kmzData, setKmzData] = useState(null)

  const handleFileUpload = async (event: React.ChangeEvent<HTMLInputElement>) => {
    const file = event.target.files?.[0]
    if (!file) return

    try {
      const response = new Response(file)
      const data = await kmzToJson(response)
      setKmzData(data)
    } catch (error) {
      console.error('KMZ 변환 오류:', error)
    }
  }

  const generateKmz = async () => {
    try {
      const kmzBlob = await jsonToKmz(kmzData)
      // 다운로드 로직...
    } catch (error) {
      console.error('KMZ 생성 오류:', error)
    }
  }

  return (
    <div>
      <input type="file" onChange={handleFileUpload} accept=".kmz" />
      <button onClick={generateKmz}>KMZ 생성</button>
      {kmzData && <pre>{JSON.stringify(kmzData, null, 2)}</pre>}
    </div>
  )
}
```

## 📋 API 참조

### `kmzToJson(blobLike: Response | Blob): Promise<Record<string, any> | string>`

KMZ 파일을 JSON 객체로 변환합니다.

**매개변수:**
- `blobLike`: KMZ 파일의 Response 또는 Blob 객체

**반환값:**
- `Promise<Record<string, any> | string>`: 변환된 JSON 객체 또는 오류 메시지

### `jsonToKmz(obj: KmzFile): Promise<Blob | string>`

JSON 객체를 KMZ 파일로 변환합니다.

**매개변수:**
- `obj`: KMZ 파일로 변환할 JSON 객체

**반환값:**
- `Promise<Blob | string>`: 생성된 KMZ 파일 Blob 또는 오류 메시지

## 🏗️ 지원하는 드론 모델

- **M30/M30T**: M30 쌍광, M30T 삼광
- **M3E/M3T/M3M**: Mavic 3 시리즈
- **M3D/M3TD**: Matrice 3 시리즈
- **M300 RTK**: Matrice 300 RTK
- **M350 RTK**: Matrice 350 RTK

## 📁 파일 구조

```
dji_kmz_parser/
├── lib/                    # 빌드된 라이브러리 파일
│   ├── index.js           # ES 모듈
│   ├── index.umd.cjs      # UMD 모듈
│   └── index.d.ts         # TypeScript 타입 정의
├── packages/              # 소스 코드
│   ├── parser.ts          # 핵심 파싱 로직
│   └── typing/            # 타입 정의
│       ├── action.ts      # 액션 타입
│       ├── global.ts      # 전역 설정 타입
│       ├── point.ts       # 웨이포인트 타입
│       ├── template.ts    # 템플릿 타입
│       └── wayline.ts     # 항로 타입
└── playground/            # 테스트 플레이그라운드
```

## 🔧 개발 환경 설정

```bash
# 저장소 클론
git clone https://github.com/nullcodeRealman/dji_kmz_parser.git
cd dji_kmz_parser

# 의존성 설치
npm install

# 개발 서버 실행
npm run dev

# 라이브러리 빌드
npm run build:lib

# 프로덕션 빌드
npm run build:prod
```

## 🤝 기여하기

1. Fork the Project
2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the Branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

## 📄 라이선스

이 프로젝트는 MIT 라이선스 하에 배포됩니다. 자세한 내용은 `LICENSE` 파일을 참조하세요.

## 🆘 문제 해결

### 자주 묻는 질문

**Q: KMZ 파일이 변환되지 않아요.**
A: 파일이 올바른 DJI KMZ 형식인지 확인하세요. 파일이 손상되었거나 다른 형식일 수 있습니다.

**Q: 생성된 KMZ 파일이 DJI Pilot에서 열리지 않아요.**
A: JSON 데이터 구조가 올바른지 확인하세요. 필수 필드가 누락되었을 수 있습니다.

**Q: TypeScript 타입 오류가 발생해요.**
A: 최신 버전의 라이브러리를 사용하고 있는지 확인하세요. 타입 정의가 업데이트되었을 수 있습니다.

## 📞 지원

문제가 발생하거나 질문이 있으시면 [Issues](https://github.com/nullcodeRealman/dji_kmz_parser/issues)를 통해 문의해주세요.

---

**Made with ❤️ for DJI Drone Developers**