kopia lustrzana https://github.com/OpenDroneMap/WebODM
Expanded docs
Piero Toffanin
rodzic
9bcf0b1b74
commit
8bb294e6ae
|
|
@ -2,13 +2,13 @@
|
|||
|
||||
## How To Process Images
|
||||
|
||||
We'll explore how to process some aerial images and retrieve the results. To do that we'll need to:
|
||||
In this tutorial we'll explore how to process an orthophoto from a set of aerial images. 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)
|
||||
- Download the resulting orthophoto.
|
||||
|
||||
<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/>
|
||||
|
||||
|
|
@ -39,7 +39,7 @@ res = requests.post('http://localhost:8000/api/projects/',
|
|||
project_id = res['id']
|
||||
```
|
||||
|
||||
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. We assign a `name` to the project.
|
||||
Then we need to create a [Project](#project). 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. We also assign a `name` to our project.
|
||||
<div class="clear"></div>
|
||||
|
||||
```python
|
||||
|
|
@ -63,8 +63,8 @@ res = requests.post('http://localhost:8000/api/projects/{}/tasks/'.format(projec
|
|||
task_id = res['id']
|
||||
```
|
||||
|
||||
We can then create a <a href="#task">Task</a>. The only required parameter is a list of multiple, multipart-encoded `images`. Processing will start automatically
|
||||
as soon as a <a href="#processingnode">Processing Node</a> is available. It is possible to specify additional options by passing an `options` value, which is a JSON-encoded list of name/value pairs. Several other options are available. See the <a href="#task">Task</a> reference for more information.
|
||||
We can then create a [Task](#task). The only required parameter is a list of multiple, multipart-encoded `images`. Processing will start automatically
|
||||
as soon as a [Processing Node](#processingnode) is available. It is possible to specify additional options by passing an `options` value, which is a JSON-encoded list of name/value pairs. Several other options are available. See the [Task](#task) reference for more information.
|
||||
<div class="clear"></div>
|
||||
|
||||
```python
|
||||
|
|
@ -83,19 +83,22 @@ while True:
|
|||
time.sleep(3)
|
||||
```
|
||||
|
||||
We periodically check for the <a href="#task">Task</a> status using a loop.
|
||||
We periodically check for the [Task](#task) status using a loop.
|
||||
<div class="clear"></div>
|
||||
|
||||
```python
|
||||
res = requests.get("http://localhost:8000/api/projects/{}/tasks/{}/download/geotiff/".format(project_id, task_id),
|
||||
headers={'Authorization': 'JWT {}'.format(token)},
|
||||
stream=True)
|
||||
with open("orthophoto.tif", 'wb') as f:
|
||||
for chunk in res.iter_content(chunk_size=1024):
|
||||
if chunk:
|
||||
f.write(chunk)
|
||||
with open("orthophoto.tif", 'wb') as f:
|
||||
for chunk in res.iter_content(chunk_size=1024):
|
||||
if chunk:
|
||||
f.write(chunk)
|
||||
print("Saved ./orthophoto.tif")
|
||||
```
|
||||
|
||||
Our orthophoto is ready to be downloaded. A variety of other assets, including a dense 3D point cloud and a textured model <a href="#download">is also available</a>.
|
||||
Our orthophoto is ready to be downloaded. A variety of other assets, including a dense 3D point cloud and a textured model [are also available](#download).
|
||||
|
||||
A <a href="" target="_blank">TMS</a> layer is also made available at `http://localhost:8000/api/projects/{project_id}/tasks/{task_id}/tiles.json` for inclusion in programs such as <a href="http://leafletjs.com/" target="_blank">Leaflet</a> or <a href="http://cesiumjs.org" target="_blank">Cesium</a>.
|
||||
Congratulations! You just processed some images.
|
||||
|
||||
|
||||
|
|
@ -33,9 +33,27 @@ description | string | A more in-depth description
|
|||
|
||||
Parameter | Required | Default | Description
|
||||
--------- | -------- | ------- | -----------
|
||||
name | * | "" | Name of the project
|
||||
name | * | "" | Name of the project
|
||||
description | | "" | A more in-depth description
|
||||
|
||||
|
||||
### Update a project
|
||||
|
||||
`PATCH /api/projects/{id}/`
|
||||
|
||||
Parameter | Required | Default | Description
|
||||
--------- | -------- | ------- | -----------
|
||||
name | | "" | Name of the project
|
||||
description | | "" | A more in-depth description
|
||||
|
||||
|
||||
### Delete a project
|
||||
|
||||
`DELETE /api/projects/{id}/`
|
||||
|
||||
Upon deletion, all [Task](#task) items associated with the [Project](#project) are deleted also. The operation is irreversible.
|
||||
|
||||
|
||||
### Get list of projects
|
||||
|
||||
> Project list:
|
||||
|
|
@ -61,24 +79,29 @@ description | | "" | A more in-depth description
|
|||
}
|
||||
```
|
||||
|
||||
`GET /api/projects/?page=N`
|
||||
`GET /api/projects/`
|
||||
|
||||
If `N` is omitted, defaults to 1.
|
||||
Parameter | Required | Default | Description
|
||||
--------- | -------- | ------- | -----------
|
||||
page | | 1 | Page number
|
||||
id | | "" | Filter by id
|
||||
name | | "" | Filter by name
|
||||
description | | "" | Filter by description
|
||||
created_at | | "" | Filter by created_at
|
||||
ordering | | "" | Ordering field to sort results by
|
||||
|
||||
#### Filtering
|
||||
|
||||
`GET /api/projects/?<field>=<value>`
|
||||
#### Example: Filtering by name
|
||||
|
||||
Where field is one of: `id`, `name`, `description`, `created_at`.
|
||||
`GET /api/projects/?name=hello`
|
||||
|
||||
#### Sorting
|
||||
Retrieves projects that have a name of "hello".
|
||||
|
||||
`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.
|
||||
#### Example: Sorting
|
||||
|
||||
#### Pagination
|
||||
`GET /api/projects/?ordering=-id`
|
||||
|
||||
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.
|
||||
Sort by project ID, descending order.
|
||||
|
||||
<aside class="notice">Only the projects visible to the current user will be displayed.</aside>
|
||||
<aside class="notice">Only projects visible to the current user are returned.</aside>
|
||||
|
|
|
|||
|
|
@ -0,0 +1,9 @@
|
|||
## Status Codes
|
||||
|
||||
Status | Code | Description
|
||||
----- | ---- | -----------
|
||||
QUEUED | 10 | [Task](#task)'s files have been uploaded to a [ProcessingNode](#processingnode) and are waiting to be processed.
|
||||
RUNNING | 20 | [Task](#task) is currently being processed.
|
||||
FAILED | 30 | [Task](#task) has failed for some reason (not enough images, out of memory, Piero forgot to close a parenthesis, etc.)
|
||||
COMPLETED | 40 | [Task](#task) has completed. Assets are be ready to be downloaded.
|
||||
CANCELED | 50 | [Task](#task) was manually canceled by the user.
|
||||
|
|
@ -1,3 +1,105 @@
|
|||
## Task
|
||||
|
||||
TODO
|
||||
> Example task:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": 134,
|
||||
"project": 27,
|
||||
"processing_node": 10,
|
||||
"images_count": 48,
|
||||
"uuid": "4338d684-91b4-49a2-b907-8ba171894393",
|
||||
"name": "Task Name",
|
||||
"processing_time": 2197417,
|
||||
"auto_processing_node": false,
|
||||
"status": 40,
|
||||
"last_error": null,
|
||||
"options": [
|
||||
{
|
||||
"name": "use-opensfm-pointcloud",
|
||||
"value": true
|
||||
}
|
||||
],
|
||||
"ground_control_points": null,
|
||||
"created_at": "2017-02-18T18:01:55.402551Z",
|
||||
"pending_action": null
|
||||
}
|
||||
```
|
||||
|
||||
A [Task](#task) is the basic processing unit of WebODM. To compute an orthophoto, point cloud and textured model from a set of images, you need to create a [Task](#task).
|
||||
|
||||
Field | Type | Description
|
||||
----- | ---- | -----------
|
||||
id | int | Unique identifier
|
||||
project | int | [Project](#project) ID the task belongs to
|
||||
processing_node | int | The ID of the [Processing Node](#processingnode) this task has been assigned to, or `null` if no [Processing Node](#processingnode) has been assigned.
|
||||
images_count | int | Number of images
|
||||
uuid | string | Unique identifier assigned by a [Processing Node](#processingnode) once processing has started.
|
||||
name | string | User defined name for the task
|
||||
processing_time | int | Milliseconds that have elapsed since the start of processing, or `-1` if no information is available. Useful for displaying a time status report to the user.
|
||||
auto_processing_node | boolean | Whether WebODM should automatically assign the next available [Processing Node](#processingnode) to process this [Task](#task). A user can set this to `false` to manually choose a [Processing Node](#processingnode).
|
||||
status | int | One of [Status Codes](#status-codes), or `null` if no status is available.
|
||||
last_error | string | The last error message reported by a [Processing Node](#processingnode) in case of processing failure.
|
||||
options | JSON[] | JSON-encoded list of name/value pairs, where each pair represents a command line option to be passed to a [Processing Node](#processingnode).
|
||||
ground_control_points | string | Currently unused. See [#37](https://github.com/OpenDroneMap/WebODM/issues/37)
|
||||
created_at | string | Creation date and time
|
||||
pending_action | int | One of [Pending Actions](#pending-actions), or `null` if no pending action is set.
|
||||
|
||||
|
||||
### Create a task
|
||||
|
||||
`POST /api/projects/`
|
||||
|
||||
Parameter | Required | Default | Description
|
||||
--------- | -------- | ------- | -----------
|
||||
name | * | "" | Name of the project
|
||||
description | | "" | A more in-depth description
|
||||
|
||||
|
||||
### Update a task
|
||||
|
||||
`PATCH /api/projects/{id}/`
|
||||
|
||||
Parameter | Required | Default | Description
|
||||
--------- | -------- | ------- | -----------
|
||||
name | | "" | Name of the project
|
||||
description | | "" | A more in-depth description
|
||||
|
||||
|
||||
### Delete a task
|
||||
|
||||
`DELETE /api/projects/{id}/`
|
||||
|
||||
Upon deletion, all <a href="#task">Task</a> items associated with the <a href="#project">Project</a> are deleted also. The operation is irreversible.
|
||||
|
||||
|
||||
### Get list of tasks
|
||||
|
||||
> Task list:
|
||||
|
||||
```json
|
||||
{
|
||||
}
|
||||
```
|
||||
|
||||
`GET /api/projects/`
|
||||
|
||||
Parameter | Required | Default | Description
|
||||
--------- | -------- | ------- | -----------
|
||||
page | | 1 | Page number
|
||||
id | | "" | Filter by id
|
||||
name | | "" | Filter by name
|
||||
description | | "" | Filter by description
|
||||
created_at | | "" | Filter by created_at
|
||||
ordering | | "" | Ordering field to sort results by
|
||||
|
||||
|
||||
## Pending Actions
|
||||
|
||||
In some circumstances, a [Task](#task) can have a pending action. When this happens, an action is soon to be performed on it.
|
||||
|
||||
Pending Action | Code | Description
|
||||
----- | ---- | -----------
|
||||
CANCEL | 1 | About to be canceled
|
||||
REMOVE | 2 | About to be removed
|
||||
RESTART | 3 | About to be restarted
|
||||
|
|
|
|||
|
|
@ -0,0 +1 @@
|
|||
At this point a TMS layer is also made available at `http://localhost:8000/api/projects/{project_id}/tasks/{task_id}/tiles.json` for inclusion in programs such as [Leaflet](http://leafletjs.com/) or [Cesium](http://cesiumjs.org).
|
||||
|
|
@ -16,4 +16,5 @@ includes:
|
|||
- reference/authentication
|
||||
- reference/project
|
||||
- reference/task
|
||||
- reference/status_codes
|
||||
---
|
||||
|
|
|
|||
Ładowanie…
Reference in New Issue