kopia lustrzana https://github.com/OpenDroneMap/WebODM
Reorganized docs in subdocuments, started writing first example, quickstart
Piero Toffanin
rodzic
27fca00c50
commit
954caf6a0d
|
|
@ -0,0 +1,27 @@
|
||||||
|
'''
|
||||||
|
This Source Code Form is subject to the terms of the Mozilla
|
||||||
|
Public License, v. 2.0. If a copy of the MPL was not
|
||||||
|
distributed with this file, You can obtain one at
|
||||||
|
https://mozilla.org/MPL/2.0/.
|
||||||
|
'''
|
||||||
|
|
||||||
|
# How to authenticate and process drone images using WebODM
|
||||||
|
import requests
|
||||||
|
res = requests.post('http://localhost:8000/api/token-auth/',
|
||||||
|
data={'username': 'admin',
|
||||||
|
'password': 'admin'}).json()
|
||||||
|
if 'token' in res:
|
||||||
|
print("Logged-in!")
|
||||||
|
token = res['token']
|
||||||
|
|
||||||
|
res = requests.post('http://localhost:8000/api/projects/',
|
||||||
|
headers={'Authorization': 'JWT {}'.format(token)},
|
||||||
|
data={'name': 'Hello WebODM!'}).json()
|
||||||
|
if 'id' in res:
|
||||||
|
print("Created project: {}".format(res))
|
||||||
|
project_id = res['id']
|
||||||
|
else:
|
||||||
|
print("Cannot create project: {}".format(res))
|
||||||
|
else:
|
||||||
|
print("Invalid credentials!")
|
||||||
|
|
||||||
|
|
@ -0,0 +1,5 @@
|
||||||
|
# Introduction
|
||||||
|
|
||||||
|
[WebODM](https://github.com/OpenDroneMap/WebODM) is a free, user-friendly, extendable application and API for drone image processing. It generates georeferenced maps, point clouds and textured 3D models from aerial images.
|
||||||
|
|
||||||
|
Developers can leverage this API to extend the functionality of [WebODM](https://github.com/OpenDroneMap/WebODM) or integrate it with existing software like [QGIS](http://www.qgis.org/) or [AutoCAD](http://www.autodesk.com/products/autocad/overview).
|
||||||
|
|
@ -0,0 +1,39 @@
|
||||||
|
# Quickstart
|
||||||
|
|
||||||
|
## How To Process Images
|
||||||
|
|
||||||
|
We'll explore how to process some aerial images and retrieve the results. To do that we'll need to:
|
||||||
|
|
||||||
|
- Authenticate
|
||||||
|
- Create a [Project](#project). Projects are a way to group together related [Task](#task) items
|
||||||
|
- Upload some images to create a [Task](#task)
|
||||||
|
- Check for [Task](#task) progress. Photogrammetry can take a long time, so results could take a few minutes to a few hours to be processed.
|
||||||
|
- Download an orthophoto from a successful [Task](#task)
|
||||||
|
|
||||||
|
<aside class="notice">Most of the examples in this document use <a href="http://docs.python-requests.org/en/latest/index.html" target="_blank">requests</a>. Make sure it's installed before running any code:<br/><br/>
|
||||||
|
|
||||||
|
<pre class="higlight shell">
|
||||||
|
$ pip install requests
|
||||||
|
</pre>
|
||||||
|
</aside>
|
||||||
|
|
||||||
|
```python
|
||||||
|
import requests
|
||||||
|
res = requests.post('http://localhost:8000/api/token-auth/',
|
||||||
|
data={'username': 'admin',
|
||||||
|
'password': 'admin'}).json()
|
||||||
|
```
|
||||||
|
|
||||||
|
First, we <a href="#authenticate">authenticate</a> with WebODM. A `token` is returned when authentication is successful.
|
||||||
|
<div class="clear"></div>
|
||||||
|
|
||||||
|
```python
|
||||||
|
if 'token' in res:
|
||||||
|
token = res['token']
|
||||||
|
res = requests.post('http://localhost:8000/api/projects/',
|
||||||
|
headers={'Authorization': 'JWT {}'.format(token)},
|
||||||
|
data={'name': 'Hello WebODM!'}).json()
|
||||||
|
```
|
||||||
|
|
||||||
|
Then we need to create a <a href="#project">Project</a>. We pass our `token` via the `Authorization` header. If we forget to pass this header, the system will not authenticate us and will refuse to process the request. `name` is the name we assign to the project.
|
||||||
|
<div class="clear"></div>
|
||||||
|
|
@ -0,0 +1,36 @@
|
||||||
|
# Reference
|
||||||
|
|
||||||
|
## Authentication
|
||||||
|
|
||||||
|
> Get authentication token:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -X POST -d "username=testuser&password=testpass" http://localhost:8000/api/token-auth/
|
||||||
|
|
||||||
|
{"token":"eyJ0eXAiO..."}
|
||||||
|
```
|
||||||
|
|
||||||
|
> Use authentication token:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -H "Authorization: JWT <your_token>" http://localhost:8000/api/projects/
|
||||||
|
|
||||||
|
{"count":13, ...}
|
||||||
|
```
|
||||||
|
|
||||||
|
`POST /api/token-auth/`
|
||||||
|
|
||||||
|
Field | Type | Description
|
||||||
|
----- | ---- | -----------
|
||||||
|
username | string | Username
|
||||||
|
password | string | Password
|
||||||
|
|
||||||
|
To access the API, you need to provide a valid username and password. You can create users from WebODM's Administration page.
|
||||||
|
|
||||||
|
If authentication is successful, you will be issued a token. All API calls should include the following header:
|
||||||
|
|
||||||
|
Header |
|
||||||
|
------ |
|
||||||
|
Authorization: JWT `your_token` |
|
||||||
|
|
||||||
|
The token expires after a set amount of time. The expiration time is dependent on WebODM's settings. You will need to request another token when a token expires.
|
||||||
|
|
@ -0,0 +1,84 @@
|
||||||
|
## Project
|
||||||
|
|
||||||
|
> Example project:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"id": 2,
|
||||||
|
"tasks": [
|
||||||
|
7,
|
||||||
|
6,
|
||||||
|
5
|
||||||
|
],
|
||||||
|
"created_at": "2016-12-07T02:09:28.515319Z",
|
||||||
|
"name": "Test",
|
||||||
|
"description": ""
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
A [Project](#project) is a collection of [Task](#task) items.
|
||||||
|
|
||||||
|
Field | Type | Description
|
||||||
|
----- | ---- | -----------
|
||||||
|
id | int | Unique identifier
|
||||||
|
tasks | int[] | List of task IDs associated with this project
|
||||||
|
created_at | string | Creation date and time
|
||||||
|
name | string | Name of the project
|
||||||
|
description | string | A more in-depth description
|
||||||
|
|
||||||
|
|
||||||
|
### Create a project
|
||||||
|
|
||||||
|
`POST /api/projects/`
|
||||||
|
|
||||||
|
Parameter | Required | Default | Description
|
||||||
|
--------- | -------- | ------- | -----------
|
||||||
|
name | * | "" | Name of the project
|
||||||
|
description | | "" | A more in-depth description
|
||||||
|
|
||||||
|
### Get list of projects
|
||||||
|
|
||||||
|
> Project list:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"count": 1,
|
||||||
|
"next": null,
|
||||||
|
"previous": null,
|
||||||
|
"results": [
|
||||||
|
{
|
||||||
|
"id": 2,
|
||||||
|
"tasks": [
|
||||||
|
7,
|
||||||
|
6,
|
||||||
|
5
|
||||||
|
],
|
||||||
|
"created_at": "2016-12-07T02:09:28.515319Z",
|
||||||
|
"name": "Test",
|
||||||
|
"description": ""
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
`GET /api/projects/?page=N`
|
||||||
|
|
||||||
|
If `N` is omitted, defaults to 1.
|
||||||
|
|
||||||
|
#### Filtering
|
||||||
|
|
||||||
|
`GET /api/projects/?<field>=<value>`
|
||||||
|
|
||||||
|
Where field is one of: `id`, `name`, `description`, `created_at`.
|
||||||
|
|
||||||
|
#### Sorting
|
||||||
|
|
||||||
|
`GET /api/projects/?ordering=<field>`
|
||||||
|
|
||||||
|
Where field is one of: `id`, `name`, `description`, `created_at`. Results are sorted in ascending order. Placing a minus `-` sign, e.g. `-created_at` sorts in descending order.
|
||||||
|
|
||||||
|
#### Pagination
|
||||||
|
|
||||||
|
The project list is paginated. Items are stored in `results`. `count` is the total number of items. `next` and `previous` are links to retrieve the next and previous page of results, or null.
|
||||||
|
|
||||||
|
<aside class="notice">Only the projects visible to the current user will be displayed.</aside>
|
||||||
|
|
@ -0,0 +1,3 @@
|
||||||
|
## Task
|
||||||
|
|
||||||
|
TODO
|
||||||
|
|
@ -9,148 +9,11 @@ toc_footers:
|
||||||
- <a href='https://github.com/OpenDroneMap/OpenDroneMap'>OpenDroneMap on GitHub</a>
|
- <a href='https://github.com/OpenDroneMap/OpenDroneMap'>OpenDroneMap on GitHub</a>
|
||||||
|
|
||||||
search: true
|
search: true
|
||||||
|
|
||||||
|
includes:
|
||||||
|
- introduction
|
||||||
|
- quickstart
|
||||||
|
- reference/authentication
|
||||||
|
- reference/project
|
||||||
|
- reference/task
|
||||||
---
|
---
|
||||||
|
|
||||||
# Introduction
|
|
||||||
|
|
||||||
[WebODM](https://github.com/OpenDroneMap/WebODM) is a free, user-friendly, extendable application and API for drone image processing. It generates georeferenced maps, point clouds and textured 3D models from aerial images.
|
|
||||||
|
|
||||||
Developers can leverage this API to extend the functionality of [WebODM](https://github.com/OpenDroneMap/WebODM) or integrate it with existing software like [QGIS](http://www.qgis.org/) or [AutoCAD](http://www.autodesk.com/products/autocad/overview).
|
|
||||||
|
|
||||||
# Quickstart
|
|
||||||
|
|
||||||
## How To Process Images
|
|
||||||
|
|
||||||
We'll explore how to process some aerial images and retrieve the results. To do that we'll need to:
|
|
||||||
|
|
||||||
- Authenticate
|
|
||||||
- Create a [Project](#project). Projects are a way to group together related [Task](#task) items
|
|
||||||
- Upload some images to create a [Task](#task)
|
|
||||||
- Check for [Task](#task) progress. Photogrammetry can take a long time, so results could take a few minutes to a few hours to be processed.
|
|
||||||
- Download an orthophoto from a successful [Task](#task)
|
|
||||||
|
|
||||||
# Reference
|
|
||||||
|
|
||||||
## Authentication
|
|
||||||
|
|
||||||
> Get authentication token:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
curl -X POST -d "username=testuser&password=testpass" http://localhost:8000/api/token-auth/
|
|
||||||
|
|
||||||
{"token":"eyJ0eXAiO..."}
|
|
||||||
```
|
|
||||||
|
|
||||||
> Use authentication token:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
curl -H "Authorization: JWT <your_token>" http://localhost:8000/api/projects/
|
|
||||||
|
|
||||||
{"count":13, ...}
|
|
||||||
```
|
|
||||||
|
|
||||||
`POST /api/token-auth/`
|
|
||||||
|
|
||||||
Field | Type | Description
|
|
||||||
----- | ---- | -----------
|
|
||||||
username | string | Username
|
|
||||||
password | string | Password
|
|
||||||
|
|
||||||
To access the API, you need to provide a valid username and password. You can create users from WebODM's Administration page.
|
|
||||||
|
|
||||||
If authentication is successful, you will be issued a token. All API calls should include the following header:
|
|
||||||
|
|
||||||
Header |
|
|
||||||
------ |
|
|
||||||
Authorization: JWT `your_token` |
|
|
||||||
|
|
||||||
The token expires after a set amount of time. The expiration time is dependent on WebODM's settings. You will need to request another token when a token expires.
|
|
||||||
|
|
||||||
## Project
|
|
||||||
|
|
||||||
> Example project:
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"id": 2,
|
|
||||||
"tasks": [
|
|
||||||
7,
|
|
||||||
6,
|
|
||||||
5
|
|
||||||
],
|
|
||||||
"created_at": "2016-12-07T02:09:28.515319Z",
|
|
||||||
"name": "Test",
|
|
||||||
"description": ""
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
A [Project](#project) is a collection of [Task](#task) items.
|
|
||||||
|
|
||||||
Field | Type | Description
|
|
||||||
----- | ---- | -----------
|
|
||||||
id | int | Unique identifier
|
|
||||||
tasks | int[] | List of task IDs associated with this project
|
|
||||||
created_at | string | Creation date and time
|
|
||||||
name | string | Name of the project
|
|
||||||
description | string | A more in-depth description
|
|
||||||
|
|
||||||
|
|
||||||
### Create a project
|
|
||||||
|
|
||||||
`POST /api/projects/`
|
|
||||||
|
|
||||||
Parameter | Required | Default | Description
|
|
||||||
--------- | -------- | ------- | -----------
|
|
||||||
name | * | "" | Name of the project
|
|
||||||
description | | "" | A more in-depth description
|
|
||||||
|
|
||||||
### Get list of projects
|
|
||||||
|
|
||||||
> Project list:
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"count": 1,
|
|
||||||
"next": null,
|
|
||||||
"previous": null,
|
|
||||||
"results": [
|
|
||||||
{
|
|
||||||
"id": 2,
|
|
||||||
"tasks": [
|
|
||||||
7,
|
|
||||||
6,
|
|
||||||
5
|
|
||||||
],
|
|
||||||
"created_at": "2016-12-07T02:09:28.515319Z",
|
|
||||||
"name": "Test",
|
|
||||||
"description": ""
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
`GET /api/projects/?page=N`
|
|
||||||
|
|
||||||
If `N` is omitted, defaults to 1.
|
|
||||||
|
|
||||||
#### Filtering
|
|
||||||
|
|
||||||
`GET /api/projects/?<field>=<value>`
|
|
||||||
|
|
||||||
Where field is one of: `id`, `name`, `description`, `created_at`.
|
|
||||||
|
|
||||||
#### Sorting
|
|
||||||
|
|
||||||
`GET /api/projects/?ordering=<field>`
|
|
||||||
|
|
||||||
Where field is one of: `id`, `name`, `description`, `created_at`. Results are sorted in ascending order. Placing a minus `-` sign, e.g. `-created_at` sorts in descending order.
|
|
||||||
|
|
||||||
#### Pagination
|
|
||||||
|
|
||||||
The project list is paginated. Items are stored in `results`. `count` is the total number of items. `next` and `previous` are links to retrieve the next and previous page of results, or null.
|
|
||||||
|
|
||||||
<aside class="notice">Only the projects visible to the current user will be displayed.</aside>
|
|
||||||
|
|
||||||
## Task
|
|
||||||
|
|
||||||
TODO
|
|
||||||
|
|
@ -12,7 +12,7 @@
|
||||||
|
|
||||||
var makeToc = function() {
|
var makeToc = function() {
|
||||||
global.toc = $("#toc").tocify({
|
global.toc = $("#toc").tocify({
|
||||||
selectors: 'h1, h2',
|
selectors: 'h1, h2, h3',
|
||||||
extendPage: false,
|
extendPage: false,
|
||||||
theme: 'none',
|
theme: 'none',
|
||||||
smoothScroll: false,
|
smoothScroll: false,
|
||||||
|
|
|
||||||
|
|
@ -476,6 +476,11 @@ html, body {
|
||||||
background: $aside-notice-bg;
|
background: $aside-notice-bg;
|
||||||
line-height: 1.6;
|
line-height: 1.6;
|
||||||
|
|
||||||
|
pre{
|
||||||
|
float: none;
|
||||||
|
padding: 6px 10px;
|
||||||
|
}
|
||||||
|
|
||||||
&.warning {
|
&.warning {
|
||||||
background-color: $aside-warning-bg;
|
background-color: $aside-warning-bg;
|
||||||
text-shadow: 0 1px 0 lighten($aside-warning-bg, 15%);
|
text-shadow: 0 1px 0 lighten($aside-warning-bg, 15%);
|
||||||
|
|
@ -562,6 +567,16 @@ html, body {
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
.tocify-subheader {
|
||||||
|
.tocify-subheader {
|
||||||
|
.tocify-item>a {
|
||||||
|
// Styling here for a level 2 nesting. For example ->
|
||||||
|
padding-left: $nav-padding + $nav-indent * 2;
|
||||||
|
font-size: 12px;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
////////////////////////////////////////////////////////////////////////////////
|
////////////////////////////////////////////////////////////////////////////////
|
||||||
// RESPONSIVE DESIGN
|
// RESPONSIVE DESIGN
|
||||||
////////////////////////////////////////////////////////////////////////////////
|
////////////////////////////////////////////////////////////////////////////////
|
||||||
|
|
|
||||||
Ładowanie…
Reference in New Issue