| Name | djikmz JSON |
| Version |
0.1.0
JSON |
| download |
| home_page | None |
| Summary | A Python package for generating DJI task plan KMZ files with type safety and integrity checks |
| upload_time | 2025-07-16 05:44:50 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | MIT |
| keywords |
dji
kmz
drone
task-plan
waypoint
kml
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# DjiKMZ - DJI Task Plan KMZ File Generator
> **⚠️ DEVELOPMENT STATUS NOTICE**
>
> This project is currently in **active development and testing phase**. Due to time and resource constraints, real-world flight testing has only covered partial functionality and drone models. (Mostly M350)
>
> **Please use with caution in production environments.** We strongly recommend thorough testing/validation on controller before field deployment.
>
> 🤝 **Contributions and bug reports are welcome!** Help us improve the library by:
> - Testing with different drone models
> - Reporting issues and edge cases
> - Contributing code improvements
> - Sharing real-world usage experiences
A Python package for generating DJI task plan KMZ files with comprehensive type safety, validation, and integrity checks.
## Goal
- 🛡️ **Type Safety**: Full type hints and Pydantic models for all data structures
- ✅ **Validation**: Comprehensive validation of waypoints, coordinates, and flight parameters
- 🔒 **Integrity Checks**: Built-in validation for DJI-specific constraints and limits
- 📦 **KMZ Generation**: Generate valid KMZ files compatible with DJI flight planning software
- 🎯 **Abstraction**: High-level API for easy waypoint and mission creation
## Installation
```bash
pip install djikmz
```
## Quick Start
```python
from djikmz import DroneTask
# Create a mission
mission = (DroneTask("M350", "Survey Pilot")
.name("Basic Survey")
.payload("P1")
.speed(8.0)
.altitude(75.0)
.fly_to(37.7749, -122.4194)
.take_photo("point0")
.hover(2.0)
.fly_to(37.7750, -122.4195)
.take_photo("point1"))
# Generate KMZ
mission.to_kmz("mission.kmz")
```
## Supported Drone Models
- M350 (Matrice 350 RTK)
- M300 (Matrice 300 RTK)
- M30/M30T (Matrice 30 Series)
- M3E/M3T/M3M (Mavic 3 Enterprise Series)
- M3D/M3TD (Mavic 3 Classic Series)
- Other drones may be added in future releases.
## API Reference
### Task Builder API
```python
from djikmz import DroneTask
# TaskBuilder API - Primary interface
mission = DroneTask(drone_model, pilot_name)
.payload(payload_model) # Optional payload model
.name(mission_name)
.speed(m_per_sec)
.altitude(meters)
# Flight commands
.fly_to(lat, lon, height=None) # Optional height for altitude
# waypoint settings
.height(meters)
.speed(m_per_sec)
.turn_mode("turn_at_point"|"early_turn"|"curve_and_stop"|"curve_and_pass")
# Camera actions
.take_photo(label)
.start_recording()
.stop_recording()
# Hover
.hover(seconds)
# Aircraft Heading
.heading(angle)
# Gimbal control (absolute positioning)
.gimbal_down(45) # Point down to 45° from forward
.gimbal_up(30) # Point up to 30° from forward
.gimbal_front() # Point straight forward (0°)
.gimbal_pitch(-90) # Precise pitch: -90° (straight down)
.gimbal_yaw(180) # Precise yaw: 180° (facing south)
.gimbal_rotate(pitch=-45, yaw=90) # Combined rotation
# Save to a ready to use Dji KMZ file
mission.to_kmz(file_path)
# Or generate KML for further processing
mission.build() -> KML
```
### Advanced Model Access
```python
from djikmz.model import KML, Waypoint, DroneModel
from djikmz.model.action import TakePhotoAction, HoverAction
# For direct model manipulation and custom integrations
waypoint = Waypoint(lat=37.7749, lon=-122.4194)
action = TakePhotoAction(action_id=1)
```
### Validation
DjiKMZ provides comprehensive validation:
- **Coordinates**: Latitude [-90,90], Longitude [-180,180]
- **Drone Limits**: Speed, altitude, and capability validation
- **DJI Standards**: Action IDs, waypoint limits, XML structure
### TODOs
- Load existing KMZ files and parse waypoints
- Task modifications
## Development
```bash
# Clone the repository
git clone https://github.com/yourusername/djikmz.git
cd djikmz
# Install in development mode
pip install -e ".[dev]"
# Run tests
pytest
```
Raw data
{
"_id": null,
"home_page": null,
"name": "djikmz",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "dji, kmz, drone, task-plan, waypoint, kml",
"author": null,
"author_email": "Zeyu Zhang <andrew.zh@live.com>",
"download_url": "https://files.pythonhosted.org/packages/7d/14/8841aa02ae43fa67c7ed75d99ac1ff1fe71a8fe5dc4b52586c0f7d25da89/djikmz-0.1.0.tar.gz",
"platform": null,
"description": "# DjiKMZ - DJI Task Plan KMZ File Generator\n\n> **\u26a0\ufe0f DEVELOPMENT STATUS NOTICE**\n> \n> This project is currently in **active development and testing phase**. Due to time and resource constraints, real-world flight testing has only covered partial functionality and drone models. (Mostly M350)\n> \n> **Please use with caution in production environments.** We strongly recommend thorough testing/validation on controller before field deployment.\n> \n> \ud83e\udd1d **Contributions and bug reports are welcome!** Help us improve the library by:\n> - Testing with different drone models\n> - Reporting issues and edge cases \n> - Contributing code improvements\n> - Sharing real-world usage experiences\n\nA Python package for generating DJI task plan KMZ files with comprehensive type safety, validation, and integrity checks.\n\n## Goal\n\n- \ud83d\udee1\ufe0f **Type Safety**: Full type hints and Pydantic models for all data structures\n- \u2705 **Validation**: Comprehensive validation of waypoints, coordinates, and flight parameters\n- \ud83d\udd12 **Integrity Checks**: Built-in validation for DJI-specific constraints and limits\n- \ud83d\udce6 **KMZ Generation**: Generate valid KMZ files compatible with DJI flight planning software\n- \ud83c\udfaf **Abstraction**: High-level API for easy waypoint and mission creation\n\n## Installation\n\n```bash\npip install djikmz\n```\n\n## Quick Start\n\n```python\nfrom djikmz import DroneTask\n\n# Create a mission\nmission = (DroneTask(\"M350\", \"Survey Pilot\")\n .name(\"Basic Survey\") \n .payload(\"P1\")\n .speed(8.0)\n .altitude(75.0)\n .fly_to(37.7749, -122.4194)\n .take_photo(\"point0\")\n .hover(2.0)\n .fly_to(37.7750, -122.4195)\n .take_photo(\"point1\"))\n\n# Generate KMZ\nmission.to_kmz(\"mission.kmz\")\n```\n\n## Supported Drone Models\n\n- M350 (Matrice 350 RTK)\n- M300 (Matrice 300 RTK) \n- M30/M30T (Matrice 30 Series)\n- M3E/M3T/M3M (Mavic 3 Enterprise Series)\n- M3D/M3TD (Mavic 3 Classic Series)\n- Other drones may be added in future releases.\n\n## API Reference\n\n### Task Builder API\n```python\nfrom djikmz import DroneTask\n\n# TaskBuilder API - Primary interface\nmission = DroneTask(drone_model, pilot_name)\n .payload(payload_model) # Optional payload model\n .name(mission_name)\n .speed(m_per_sec)\n .altitude(meters)\n\n# Flight commands \n .fly_to(lat, lon, height=None) # Optional height for altitude\n\n# waypoint settings\n .height(meters) \n .speed(m_per_sec)\n .turn_mode(\"turn_at_point\"|\"early_turn\"|\"curve_and_stop\"|\"curve_and_pass\")\n\n# Camera actions\n .take_photo(label)\n .start_recording()\n .stop_recording()\n\n# Hover\n .hover(seconds)\n\n# Aircraft Heading\n .heading(angle) \n\n# Gimbal control (absolute positioning)\n .gimbal_down(45) # Point down to 45\u00b0 from forward\n .gimbal_up(30) # Point up to 30\u00b0 from forward \n .gimbal_front() # Point straight forward (0\u00b0)\n .gimbal_pitch(-90) # Precise pitch: -90\u00b0 (straight down)\n .gimbal_yaw(180) # Precise yaw: 180\u00b0 (facing south)\n .gimbal_rotate(pitch=-45, yaw=90) # Combined rotation\n\n# Save to a ready to use Dji KMZ file\nmission.to_kmz(file_path) \n\n# Or generate KML for further processing\nmission.build() -> KML\n\n```\n\n### Advanced Model Access\n```python\nfrom djikmz.model import KML, Waypoint, DroneModel\nfrom djikmz.model.action import TakePhotoAction, HoverAction\n\n# For direct model manipulation and custom integrations\nwaypoint = Waypoint(lat=37.7749, lon=-122.4194)\naction = TakePhotoAction(action_id=1)\n```\n\n### Validation \n\nDjiKMZ provides comprehensive validation:\n- **Coordinates**: Latitude [-90,90], Longitude [-180,180]\n- **Drone Limits**: Speed, altitude, and capability validation\n- **DJI Standards**: Action IDs, waypoint limits, XML structure \n\n### TODOs\n- Load existing KMZ files and parse waypoints\n- Task modifications\n\n## Development\n\n```bash\n# Clone the repository\ngit clone https://github.com/yourusername/djikmz.git\ncd djikmz\n\n# Install in development mode\npip install -e \".[dev]\"\n\n# Run tests\npytest\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Python package for generating DJI task plan KMZ files with type safety and integrity checks",
"version": "0.1.0",
"project_urls": {
"Homepage": "https://github.com/zhzyx/djikmz",
"Issues": "https://github.com/zhzyx/djikmz/issues",
"Repository": "https://github.com/zhzyx/djikmz"
},
"split_keywords": [
"dji",
" kmz",
" drone",
" task-plan",
" waypoint",
" kml"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "489429cde6be31f2c3b7ef586a98bca1f7b81d0d785f64e129405747f9bbf99f",
"md5": "216d769830558412828e6bb979ab8102",
"sha256": "5c9e180cc36d7b2671372b461a1ba568d85be19a859fc05a62afe7ea10a44979"
},
"downloads": -1,
"filename": "djikmz-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "216d769830558412828e6bb979ab8102",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 36258,
"upload_time": "2025-07-16T05:44:48",
"upload_time_iso_8601": "2025-07-16T05:44:48.536546Z",
"url": "https://files.pythonhosted.org/packages/48/94/29cde6be31f2c3b7ef586a98bca1f7b81d0d785f64e129405747f9bbf99f/djikmz-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "7d148841aa02ae43fa67c7ed75d99ac1ff1fe71a8fe5dc4b52586c0f7d25da89",
"md5": "2872b01906e67e15c62fc23af54c86bf",
"sha256": "765693b89ccc000081c6dc76b489d3a8853050bcac20e8f54b646b58fb266424"
},
"downloads": -1,
"filename": "djikmz-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "2872b01906e67e15c62fc23af54c86bf",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 58037,
"upload_time": "2025-07-16T05:44:50",
"upload_time_iso_8601": "2025-07-16T05:44:50.215916Z",
"url": "https://files.pythonhosted.org/packages/7d/14/8841aa02ae43fa67c7ed75d99ac1ff1fe71a8fe5dc4b52586c0f7d25da89/djikmz-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-16 05:44:50",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "zhzyx",
"github_project": "djikmz",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "djikmz"
}
