Skip to content

API Reference

Jump to bottom
kencoken edited this page Dec 2, 2014 · 3 revisions

Introduction

The CPU Visor Service can be launched by running the ./cpuvisor_service binary, and operates via Google Protobuf messages sent via ZMQ. An sample Python client is provided: pyclient/visor_client.py along with an example of its use test_client.py.

In general, the non-blocking versions of the API functions should be preferred, and the calls used in conjunction with the service notifications documented on the notifications page.

API Reference

All requests are made with a RPCReq protobuf object with at a minimum the request_string set to the name of the API function, plus any other function-specific required fields set:

{
  request_string = <function_name>,
  <any other required fields>
}

The response from the server will be a RPCRep protobuf object. If successful, at minimum the success field will be set to true, and the ID of the processed query will be returned, along with any other function-specific returned fields:

{
  success: true,
  query_id: "e8b2ee8e227118a132a76b34640ac1eb",
  <any other returned fields>
}

If the request fails, then the success field will be set to false, and details of the error will be returned in the err_msg field. In general, the ID of the processed query will also be returned:

{
  success: false,
  query_id: "e8b2ee8e227118a132a76b34640ac1eb",
  err_msg: "The request timed out"
}

Full documentation for all API functions are given below, detailing the extra fields required in RPCReq and returned in RPCRep in each case. The full definitions of the RPCReq and RPCRep protobuf objects, along with the other nested protobuf objects referenced below, can be found in src/proto/cpuvisor_srv.proto.

API Functions

####>> start_query([tag])

Starts a new query, returning a unique string identifier which can subsequently be used to track its progress and finally return the query results.

######Input Parameters

Can optionally set a tag using the RPCReq protobuf object:

{
  [tag: "car"]
}

######Output Parameters

No additional output parameters. A RPCRep protobuf object is returned with ID field populated with the newly generated ID.

####>> set_tag(query_id, tag)

Set the descriptive tag associated with a query, if it has not already been specified in the start_query call. This is used as a human readable identifier when, for example, downloading images from the web.

######Input Parameters

Specify the query ID and new tag value in the RPCReq object:

{
  query_id: "e8b2ee8e227118a132a76b34640ac1eb",
  tag: "car"
}

######Output Parameters

No additional output parameters. A RPCRep protobuf object is returned.

####>> add_trs(query_id, urls)

Add training samples to a query from a list of one or more urls. The tag parameter of the query must have been set before calling this method (either via start_query or set_tag functions) as this is used to determine the local path to which the images are downloaded before their features are computed.

######Input Parameters

Specify the query ID and image urls within a TrainImageUrls protobuf object containing a repeated urls and are_positive field. Right now only are_positive=true is supported:

{
  query_id: "e8b2ee8e227118a132a76b34640ac1eb",
  train_image_urls: { // TrainImageUrls object
    urls: [http://www.example.com/image.jpg, http://server.co.uk/image.jpg],
    are_positive: [true, true]
  }
}

######Output Parameters

No additional output parameters. A RPCRep protobuf object is returned. This function is non-blocking, and will return immediately – to detect when the URLs have all been processed, listen for a NTFY_STATE_CHANGE notification as on the notifications page. A NTFY_IMAGE_PROCESSED notification will also be issued when each individual image completes processing.

####>> add_trs_from_file(query_id, paths) / add_trs_from_file_and_wait(query_id, paths)

Add training samples to a query from a list of one or more filenames directly. It is recommended to add urls directly using add_trs, but this function is provided for additional flexibility. Unlike the add_trs method, the tag property of the query does not need to be set beforehand.

######Input Parameters

Specify the query ID and image paths on disk within a TrainImageUrls protobuf object containing a repeated urls and are_positive field. The file paths should be specified in the urls field, and right now only are_positive=true is supported:

{
  query_id: "e8b2ee8e227118a132a76b34640ac1eb",
  train_image_urls: { // TrainImageUrls object
    urls: [/path/on/disk/image.jpg, /path/on/disk/image2.jpg],
    are_positive: [true, true]
  }
}

######Output Parameters

No additional output parameters. A RPCRep protobuf object is returned. This function is non-blocking, and will return immediately – to detect when the paths have all been processed, listen for a NTFY_STATE_CHANGE notification as on the notifications page. A NTFY_IMAGE_PROCESSED notification will also be issued when each individual image completes processing. A blocking version of the function is also provided add_trs_from_file_and_wait.

####>> train(query_id) / train_and_wait(query_id)

Train a model with all training samples added for a query so far. Once this is called, no further training samples can be added and any outstanding calls to add_trs will be ignored.

######Input Parameters

Specify the query ID:

{
  query_id: "e8b2ee8e227118a132a76b34640ac1eb"
}

######Output Parameters

No additional output parameters. A RPCRep protobuf object is returned. This function is non-blocking, and will return immediately – to detect when the URLs have all been processed, listen for a NTFY_STATE_CHANGE notification as on the notifications page. A blocking version of the function is also provided train_and_wait.

####>> rank(query_id) / rank_and_wait(query_id)

Rank the target dataset using the pre-trained model. This must be called only after a call to train has been made, and the model has finished training.

######Input Parameters

Specify the query ID:

{
  query_id: "e8b2ee8e227118a132a76b34640ac1eb"
}

######Output Parameters

No additional output parameters. A RPCRep protobuf object is returned. This function is non-blocking, and will return immediately – to detect when the URLs have all been processed, listen for a NTFY_STATE_CHANGE notification as on the notifications page. A blocking version of the function is also provided rank_and_wait.

####>> get_ranking(query_id)

Retrieve the ranked list of a query. This must be called only after a call to rank has been made, and the ranking process has completed.

######Input Parameters

Specify the query ID and also optionally the page of the ranking to retrieve (by default the first page is retrieved):

{
  query_id: "e8b2ee8e227118a132a76b34640ac1eb",
  [retrieve_page: 42]
}

######Output Parameters

A RPCRep protobuf object is returned with the ranking field set to a RankedList protobuf object containing the ranking and page details.

{
  ranking: { // RankedList object
    rlist: { // RankedItem object
      path: ["dset_image_1.jpg", "dset_image_2.jpg", "dset_image_3.jpg],
      score: [4.56, 3.28, 2.83]
    },
    page: 1,
    page_count: 1000
  }
}

Repeated calls can be made to retrieve other pages of the ranking.

####>> train_rank_get_ranking(query_id)

A convenience function which calls all of train, rank and get_ranking functions above in turn in a blocking manner, returning the ranked list for a query directly.

######Input Parameters

Specify the query ID and also optionally the page of the ranking to retrieve (by default the first page is retrieved):

{
  query_id: "e8b2ee8e227118a132a76b34640ac1eb",
  [retrieve_page: 42]
}

######Output Parameters

A RPCRep protobuf object is returned with the ranking field set to a RankedList protobuf object containing the ranking and page details.

{
  ranking: { // RankedList object
    rlist: { // RankedItem object
      path: ["dset_image_1.jpg", "dset_image_2.jpg", "dset_image_3.jpg],
      score: [4.56, 3.28, 2.83]
    },
    page: 1,
    page_count: 1000
  }
}

####>> free_query(query_id)

Frees all resources related to a query in the backend. Subsequent to calling free_query, any calls using the query Id specified will fail, so make sure you do not call this function until the query data is no longer required.

######Input Parameters

Specify the query ID:

{
  query_id: "e8b2ee8e227118a132a76b34640ac1eb"
}

######Output Parameters

No additional output parameters. A RPCRep protobuf object is returned.

Clone this wiki locally