Expanded docs, examples, modified API to return full Task object definition instead of just ID

app/api/tasks.py

@@ -136,10 +136,8 @@ class TaskViewSet(viewsets.ViewSet):
             serializer.is_valid(raise_exception=True)
             serializer.save()
 
-            return Response({"id": task.id}, status=status.HTTP_201_CREATED)
+            return Response(serializer.data, status=status.HTTP_201_CREATED)
 
-        # on transaction fail
-        raise exceptions.ValidationError(detail="Cannot create task, input provided is not valid.")
 
     def update(self, request, pk=None, project_pk=None, partial=False):
         get_and_check_project(request, project_pk, ('change_project', ))

app/urls.py

@@ -15,7 +15,7 @@ urlpatterns = [
     url(r'^processingnode/([\d]+)/$', views.processing_node, name='processing_node'),
 
     url(r'^api/', include("app.api.urls")),
-    url(r'^apiviewer/', get_swagger_view(title='WebODM API'))
+    url(r'^apiviewer/', get_swagger_view(title='WebODM API')),
 ]
 
 # Test cases call boot() independently

slate/examples/process_images.py

@@ -6,10 +6,27 @@ https://mozilla.org/MPL/2.0/.
 '''
 
 # How to authenticate and process drone images using WebODM
-import requests
+import requests, sys, os, glob, json
+
+if len(sys.argv) < 2:
+	print("Usage: ./{} <path_to_images>".format(sys.argv[0]))
+	sys.exit(1)
+
+types = ("*.jpg", "*.jpeg", "*.JPG", "*.JPEG")
+images_list = []
+for t in types:
+	images_list.extend(glob.glob(os.path.join(sys.argv[1], t)))
+
+if len(images_list) < 1:
+	print("Need at least 2 images")
+	sys.exit(1)
+else:
+	print("Found {} images".format(len(images_list)))
+
 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']
@@ -20,6 +37,23 @@ if 'token' in res:
 	if 'id' in res:
 		print("Created project: {}".format(res)) 
 		project_id = res['id']
+
+		images = [('images', (os.path.basename(file), open(file, 'rb'), 'image/jpg')) for file in images_list]
+		options = json.dumps([
+			{'name': "use-opensfm-pointcloud", 'value': True},
+			{'name': "orthophoto-resolution", 'value': 24},
+		])
+		res = requests.post('http://localhost:8000/api/projects/{}/tasks/'.format(project_id), 
+					headers={'Authorization': 'JWT {}'.format(token)},
+					files=images,
+					data={
+						'options': options
+					}).json()
+
+		print("Created task: {}".format(res))
+		task_id = res['id']
+
+		
 	else:
 		print("Cannot create project: {}".format(res))
 else:

slate/source/includes/_quickstart.md

@@ -17,23 +17,52 @@ $ pip install requests
 </pre>
 </aside>
 
+<aside class="notice">
+The <a href="https://github.com/OpenDroneMap/WebODM/tree/master/slate/examples/process_images.py" target="_blank">source code</a> for this example is available on GitHub</a>.
+</aside>
+
 ```python
 import requests
 res = requests.post('http://localhost:8000/api/token-auth/', 
 					data={'username': 'admin',
 						  'password': 'admin'}).json()
+token = res['token']
 ```
 
 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()
+res = requests.post('http://localhost:8000/api/projects/', 
+					headers={'Authorization': 'JWT {}'.format(token)},
+					data={'name': 'Hello WebODM!'}).json()
+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. `name` is the name we assign to the project.
-<div class="clear"></div>
+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.
+<div class="clear"></div>
+
+```python
+images = [
+	('images', ('image1.jpg', open('image1.jpg', 'rb'), 'image/jpg')), 
+	('images', ('image2.jpg', open('image2.jpg', 'rb'), 'image/jpg')),
+	# ...
+]
+options = json.dumps([
+	{'name': "use-opensfm-pointcloud", 'value': True},
+	{'name': "orthophoto-resolution", 'value': 24},
+])
+
+res = requests.post('http://localhost:8000/api/projects/{}/tasks/'.format(project_id), 
+			headers={'Authorization': 'JWT {}'.format(token)},
+			files=images,
+			data={
+				'options': options
+			}).json()
+
+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.
+