DjiKMZ

https://github.com/zhzyx/djikmz
Admin
DjiKMZ is a Python package for generating DJI task plan KMZ files with comprehensive type safety,...
Tokens:1,693
Snippets:13
Trust Score:4.8
License:MIT
Update:3 months ago
Show doc for...
Tokens:
Raw
### Development Setup and Testing

Source: https://github.com/zhzyx/djikmz/blob/main/README.md

Instructions for cloning the repository, installing the package in development mode with extra dependencies, and running the test suite. Assumes git and Python environments are set up.

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

--------------------------------

### Install DjiKMZ Package

Source: https://github.com/zhzyx/djikmz/blob/main/README.md

Install the library using pip. This command installs the package and its dependencies.

```bash
pip install djikmz
```

--------------------------------

### Quick Start: Create and Generate a Survey Mission

Source: https://github.com/zhzyx/djikmz/blob/main/README.md

Demonstrates creating a basic survey mission with waypoints, camera actions, and hover commands, then saving it to a KMZ file. Requires importing the DroneTask class.

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

--------------------------------

### Task Builder API: Flight Commands and Settings

Source: https://github.com/zhzyx/djikmz/blob/main/README.md

Illustrates the primary interface for building flight tasks, including setting mission parameters, defining flight paths with fly_to, configuring waypoint settings, and specifying camera actions. Requires importing DroneTask.

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

--------------------------------

### Task Builder API

Source: https://github.com/zhzyx/djikmz/blob/main/README.md

The primary interface for creating and configuring drone missions. It allows for setting mission parameters, defining flight paths, and specifying camera actions.

```APIDOC
## Task Builder API

### Description
The TaskBuilder API is the primary interface for creating and configuring drone missions. It allows for setting mission parameters, defining flight paths, and specifying camera actions.

### Methods
- `DroneTask(drone_model, pilot_name)`: Initializes a new mission task.
- `.payload(payload_model)`: Sets the optional payload model.
- `.name(mission_name)`: Sets the mission name.
- `.speed(m_per_sec)`: Sets the flight speed in meters per second.
- `.altitude(meters)`: Sets the flight altitude in meters.
- `.fly_to(lat, lon, height=None)`: Navigates the drone to a specified latitude and longitude, with an optional height.
- `.height(meters)`: Sets the altitude for the next waypoint.
- `.speed(m_per_sec)`: Sets the flight speed for the next waypoint.
- `.turn_mode(mode)`: Sets the turn mode for the next waypoint. Supported modes: `"turn_at_point"`, `"early_turn"`, `"curve_and_stop"`, `"curve_and_pass"`.
- `.take_photo(label)`: Triggers taking a photo, with an optional label.
- `.start_recording()`: Starts video recording.
- `.stop_recording()`: Stops video recording.
- `.hover(seconds)`: Makes the drone hover for a specified duration.
- `.heading(angle)`: Sets the aircraft heading angle.
- `.gimbal_down(angle)`: Points the gimbal down by a specified angle from the forward direction.
- `.gimbal_up(angle)`: Points the gimbal up by a specified angle from the forward direction.
- `.gimbal_front()`: Points the gimbal straight forward (0°).
- `.gimbal_pitch(angle)`: Sets the gimbal pitch to a precise angle.
- `.gimbal_yaw(angle)`: Sets the gimbal yaw to a precise angle.
- `.gimbal_rotate(pitch, yaw)`: Sets the gimbal pitch and yaw to precise angles simultaneously.
- `.to_kmz(file_path)`: Generates and saves the mission as a KMZ file.
- `.build()`: Generates the KML representation of the mission.
```

--------------------------------

### Advanced Model Access: Direct Model Manipulation

Source: https://github.com/zhzyx/djikmz/blob/main/README.md

Shows how to access and manipulate the underlying data models directly for custom integrations or advanced use cases. Requires importing specific model classes.

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

--------------------------------

### Advanced Model Access

Source: https://github.com/zhzyx/djikmz/blob/main/README.md

Provides access to the underlying data models for direct manipulation and custom integrations.

```APIDOC
## Advanced Model Access

### Description
This section provides access to the underlying data models for direct manipulation and custom integrations. It is useful for advanced users who need to work with the data structures directly.

### Classes
- `KML`: Represents the KML file structure.
- `Waypoint`: Represents a single waypoint in the mission.
- `DroneModel`: Represents a supported drone model.
- `TakePhotoAction`: Represents a camera action to take a photo.
- `HoverAction`: Represents an action to hover the drone.
```
Tokens:
Raw