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
`

🚀 사용법

$3

`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)
}
}
`

$3

`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



`

$3

`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) => {
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 (

KMZ 생성
{kmzData &&

{JSON.stringify(kmzData, null, 2)}

}

)
}
`

📋 API 참조

$3

KMZ 파일을 JSON 객체로 변환합니다.

매개변수:
- blobLike: KMZ 파일의 Response 또는 Blob 객체

반환값:
- Promise | string>: 변환된 JSON 객체 또는 오류 메시지

$3

JSON 객체를 KMZ 파일로 변환합니다.

매개변수:
- obj: KMZ 파일로 변환할 JSON 객체

반환값:
- Promise: 생성된 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` 파일을 참조하세요.

🆘 문제 해결

$3

Q: KMZ 파일이 변환되지 않아요.
A: 파일이 올바른 DJI KMZ 형식인지 확인하세요. 파일이 손상되었거나 다른 형식일 수 있습니다.

Q: 생성된 KMZ 파일이 DJI Pilot에서 열리지 않아요.
A: JSON 데이터 구조가 올바른지 확인하세요. 필수 필드가 누락되었을 수 있습니다.

Q: TypeScript 타입 오류가 발생해요.
A: 최신 버전의 라이브러리를 사용하고 있는지 확인하세요. 타입 정의가 업데이트되었을 수 있습니다.

📞 지원

문제가 발생하거나 질문이 있으시면 Issues를 통해 문의해주세요.

---

Made with ❤️ for DJI Drone Developers