DJI KMZ Parser

DJI 드론의 KMZ 파일을 JSON으로 변환하고, JSON을 KMZ 파일로 생성할 수 있는 TypeScript 라이브러리입니다.

✨ 주요 기능

• 🔄 KMZ ↔ JSON 변환: DJI KMZ 파일과 JSON 간의 양방향 변환
• 📝 완벽한 타입 지원: TypeScript로 작성되어 타입 안전성 보장
• 🎯 DJI 호환성: DJI Pilot, DJI Flighthub 2와 완전 호환
• 🗜️ 최적화된 압축: DJI와 동일한 압축률로 파일 크기 최적화
• 🌏 한국어 문서화: 모든 주석과 타입 정의가 한국어로 번역됨

📦 설치

# npm 사용
npm i @nullcode_realman/dji_kmz_parser

🚀 사용법

1. KMZ 파일을 JSON으로 변환

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 파일로 변환

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에서 사용하기

<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에서 사용하기

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/            # 테스트 플레이그라운드

🔧 개발 환경 설정

# 저장소 클론
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를 통해 문의해주세요.

Made with ❤️ for DJI Drone Developers