diff --git a/slate/examples/process_images.py b/slate/examples/process_images.py new file mode 100644 index 00000000..36a4fd45 --- /dev/null +++ b/slate/examples/process_images.py @@ -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!") + diff --git a/slate/source/includes/_introduction.md b/slate/source/includes/_introduction.md new file mode 100644 index 00000000..eaf5d8f0 --- /dev/null +++ b/slate/source/includes/_introduction.md @@ -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). diff --git a/slate/source/includes/_quickstart.md b/slate/source/includes/_quickstart.md new file mode 100644 index 00000000..d970717b --- /dev/null +++ b/slate/source/includes/_quickstart.md @@ -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) + + + +```python +import requests +res = requests.post('http://localhost:8000/api/token-auth/', + data={'username': 'admin', + 'password': 'admin'}).json() +``` + +First, we authenticate with WebODM. A `token` is returned when authentication is successful. +
+ +```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 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. `name` is the name we assign to the project. +
\ No newline at end of file diff --git a/slate/source/includes/reference/_authentication.md b/slate/source/includes/reference/_authentication.md new file mode 100644 index 00000000..a6fea15d --- /dev/null +++ b/slate/source/includes/reference/_authentication.md @@ -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 " 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. diff --git a/slate/source/includes/reference/_project.md b/slate/source/includes/reference/_project.md new file mode 100644 index 00000000..52409bbb --- /dev/null +++ b/slate/source/includes/reference/_project.md @@ -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/?=` + +Where field is one of: `id`, `name`, `description`, `created_at`. + +#### Sorting + +`GET /api/projects/?ordering=` + +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. + + diff --git a/slate/source/includes/reference/_task.md b/slate/source/includes/reference/_task.md new file mode 100644 index 00000000..7b57430e --- /dev/null +++ b/slate/source/includes/reference/_task.md @@ -0,0 +1,3 @@ +## Task + +TODO diff --git a/slate/source/index.html.md b/slate/source/index.html.md index bb498ff1..d8047076 100644 --- a/slate/source/index.html.md +++ b/slate/source/index.html.md @@ -9,148 +9,11 @@ toc_footers: - OpenDroneMap on GitHub 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 " 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/?=` - -Where field is one of: `id`, `name`, `description`, `created_at`. - -#### Sorting - -`GET /api/projects/?ordering=` - -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. - - - -## Task - -TODO \ No newline at end of file diff --git a/slate/source/javascripts/app/_toc.js b/slate/source/javascripts/app/_toc.js index 21d08000..a54c5f82 100644 --- a/slate/source/javascripts/app/_toc.js +++ b/slate/source/javascripts/app/_toc.js @@ -12,7 +12,7 @@ var makeToc = function() { global.toc = $("#toc").tocify({ - selectors: 'h1, h2', + selectors: 'h1, h2, h3', extendPage: false, theme: 'none', smoothScroll: false, diff --git a/slate/source/stylesheets/screen.css.scss b/slate/source/stylesheets/screen.css.scss index 1d216d36..06e674b7 100644 --- a/slate/source/stylesheets/screen.css.scss +++ b/slate/source/stylesheets/screen.css.scss @@ -476,6 +476,11 @@ html, body { background: $aside-notice-bg; line-height: 1.6; + pre{ + float: none; + padding: 6px 10px; + } + &.warning { background-color: $aside-warning-bg; 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 ////////////////////////////////////////////////////////////////////////////////