Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

added http.md article

  • Loading branch information...
commit 986b757afd538758fc9a10e0c6ca214dfb2967fd 1 parent c02a389
@liuliu authored
Showing with 104 additions and 1 deletion.
  1. +3 −1 THANKS
  2. +101 −0 doc/http.md
View
4 THANKS
@@ -6,6 +6,8 @@ Michael Shapiro, for fixing libpng support on Mac OSX
Zifei Tong, for 16-bit PNG bug fix
-Michael Ledford, for fixing 0.2 version on Mac OSX
+Michael Ledford, for fixing 0.2 version on Mac OSX, and more reasonable feature detection on Mac OSX for 0.3
alantrrs, for his TLD evaluation scripts and datasets
+
+Sander Mathijs van Veen: for better makefile organization
View
101 doc/http.md
@@ -0,0 +1,101 @@
+HTTP: A REST-ful API
+====================
+
+How it works?
+-------------
+
+Go to ccv/serve. This functionality requires support of [libdispatch](http://libdispatch.macosforge.org/) and [libev](http://software.schmorp.de/pkg/libev). Luckily, these libraries are easy to install, for example, on Ubuntu 12.04 LTS, you can simply:
+
+ sudo apt-get install libdispatch-dev libev-dev
+
+and it is done. If you are on Mac OSX, you can simply:
+
+ brew install libev
+
+and it is done.
+
+On Mac OSX, you have to manually remove -ldispatch in ccv/serve/makefile, other than that, you are one make away:
+
+ cd serve/ && make && ./ccv
+
+Now, it is up and running!
+
+How can I use it?
+-----------------
+
+Following chapters assumed that you have basic understanding of curl.
+
+The HTTP API as it is now, only supports 5 major ccv functionalities: BBF, DPM, SWT, TLD and SIFT. All these APIs are discoverable, you can simply:
+
+ curl localhost:3350
+
+and it will return you the list of API endpoints that you can navigate, try one:
+
+ curl localhost:3350/dpm/detect.objects
+
+It returns:
+
+ {
+ "request":{
+ "interval":"integer",
+ "min_neighbors":"integer",
+ "model":"string",
+ "source":"blob",
+ "threshold":"number"
+ },
+ "response":[
+ {
+ "x":"integer",
+ "y":"integer",
+ "width":"integer",
+ "height":"integer",
+ "confidence":"number",
+ "parts":[
+ {
+ "x":"integer",
+ "y":"integer",
+ "width":"integer",
+ "height":"integer",
+ "confidence":"number"
+ }
+ ]
+ }
+ ]
+ }
+
+All responses from ccv are JSON encoded, like the example above. Particularly, the above JSON encodes what a POST request should look like, and what kind of JSON data structure you can expect as return. From the description, we knew that we should encode file into source field, and specify what model you want to use:
+
+ curl -F source=@"pedestrian.png" -F model="pedestrian" localhost:3350/dpm/detect.objects
+
+The above query should give you a series of detected rectangles that denotes pedestrians in the given image.
+
+ccv supports multipart-encoded parameter, as well as query strings, the above query is equivalent to:
+
+ curl -F source=@"pedestrian.png" "localhost:3350/dpm/detect.objects?model=pedestrian"
+
+Or:
+
+ curl --data-binary @"pedestrian.png" "localhost:3350/dpm/detect.objects?model=pedestrian"
+
+Any 'source' parameters in ccv HTTP API can be passed directly as HTTP body.
+
+A more advanced example would be TLD.
+
+Under the hood?
+---------------
+
+On Life-cycle of a Request
+
+Whenever you issued a HTTP request, ccv received such request with libev, in asynchronous fashion, and then dispatch a processing function to another thread with libdispatch, when the data is ready, ccv will dispatch back to main event loop and send result back. Thus, requests to ccv won't block each other. Although silly, dummy GET requests to ccv HTTP API endpoints can easily peak to around 25K requests per second, you shouldn't worry too much about its HTTP performance (you should more worry about its computer vision algorithms' performance).
+
+On Error Message
+
+ccv's HTTP endpoints doesn't provide informative error messages, if you issued a request that it cannot handle, will return 400 with 'false' in its body. It may not be a problem for most of the API endpoints, but it would be for some advanced ones.
+
+On Parameters
+
+All HTTP API's parameters can be easily interpreted through the C API documentation, ccv chooses reasonable defaults from start, so any of them are optional.
+
+On Security
+
+The HTTP API endpoints are not intended to be exposed to public Internet, you should hide these behind firewalls.
Please sign in to comment.
Something went wrong with that request. Please try again.