# ratesdk-open

**Repository Path**: thor/ratesdk-open

## Basic Information

- **Project Name**: ratesdk-open
- **Description**: No description available
- **Primary Language**: Ruby
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2014-05-26
- **Last Updated**: 2020-12-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# RATE Ruby Client Document

---

## Prerequisite

Ruby 2.0.0 or higher

## Getting started

#### Install Ruby and Ruby Gems

Windows: Download Ruby Installer [Here](http://dl.bintray.com/oneclick/rubyinstaller/rubyinstaller-2.0.0-p451.exe?direct)

Mac: if using homebrew, `brew install ruby`

Linux: `sudo apt-get install ruby`

After Ruby is installed, open a shell, and run `gem install bundler`

#### Clone the repository

```
$ git clone http://git.oschina.net/thor/ratesdk.git
$ cd ratesdk && bundle install
```

Now all the dependencies needed to use the SDK and CLI are satisfied.

## Use the CLI

Compare to using SDK, it's quite easy and convenient to use CLI, if you are doing some basic jobs.

Go to the `bin` dir.

First some basic configuration is needed, you shold see a `config.yml.example` file, copy this file to `config.yml` and open it. It looks like:

```
:host: rate.pku.edu.cn
:port: 2015
:email: xianran@pku.edu.cn
:password: '12345'
:per_page: 10
```

These config items are very understandable from their names. Remember to use your own account.

Then, run `ruby client.rb` from the same directory. Now welcome to the RATE CLI.

![shot1](screenshots/shot1.png)

RATE CLI is very powerful, you can do almost everything that you can do on the website with it. It's time for you to play with it, but I'd like to introduce some features to you.

![shot2](screenshots/shot2.png)

This is basically what you would see when choose one of the options. What you can do and what you should do is informed at the buttom panel. Almost every command is a single character.

Take Views as an example, you can *delete* item with command `d ItemID`, you can *Show Detail* with command `i ItemID`, you can *Create* new item with command `c ItemID`. For the sake of your eyes, I provide a page navigating command `<` and `>`.

Let's see how to create a benchmark

![shot3](screenshots/shot3.png)

It asks you many questions to create a benchmark. At any time, you can press `ctr-c` to cancel the create procedure.

Since create benchmark could be quite time-comsuming, there is a lovely Pacman process bar.

Another feature is that you can download many things if you detail an Algorithm, a Benchmark, or a Task. The algorithm will be downloaded just as you upload them. The benchmark will be downloaded with the benchmark.txt file and uuidTable.txt. The task will be downloaded with all the enroll and match results, the uuidTable.txt file, and the images enrolled.

I know very well that all of you want to see a better result like we do on the RATE website, so when you show a task's detail, you can press 'o'. This will open your default browser and take you to the task result web page. On this page, you can see three graphics about the algorithm's performance, and you can see match results with pictures!

![shot4](screenshots/shot4.png)

![shot5](screenshots/shot5.png)
## Use the SDK

If you want to write code to run tasks and get result, RATE SDK is your choice. But in most cases, RATE CLI is enough.

1. at any directory, download the ratesdk.rb file
2. create a .rb file, require the sdk like `require './ratesdk.rb'`
3. Write code in your .rb file
4. run it using `ruby yourscript.rb`, or just double click it on windows.

Example scripts can be found under direcotry `test`


### Usage Examples

In the first place in any of your rate scripts, you have to obtain a session from rate server.

#### Get a session

```
client = RateClient.new(host: 'localhost', port: 2015,
       email: 'xianran@pku.edu.cn', password: '12345')
```

From now on, you can use the `client` object to call rate services.

#### List things

There's lots of information you can get from a rate server, like how many samples in total, how many views I can use, etc. 

The list command is to, like it say, list them.

```
views = client.list(target: 'view')
pp views.contents
# [{"description"=>"description",
#   "generated"=>"2014-04-28 15:24:35.0",
#   "generator"=>"GenerateByImportTagGenerator",
#   "name"=>"oneview",
#   "type"=>"FINGERVEIN",
#   "uuid"=>"7afd27d0-4314-474a-bc5c-aaece54e0583",
#   "class_count"=>25,
#   "sample_count"=>75}]
benchmarks = client.list(target: 'benchmarks')
pp benchmarks.extract('name')
# => [["mybench"], ["TESTBENCH"], ["mybench"], ["mybench"], ["testbench"]]
```

You can list *view*, *benchmark*, *algorithm*, *task*

#### Info things

To get information about one object, use the info commands. You have to give an uuid to specify the object.

```
view = client.info(target: 'view', uuid: 'xxxxxxxxxxxx')
```

You can info *view*, *benchmark*, *algorithm*, *task*

#### Create things

You can create *user*, *view*, *benchmark*, *algorithm*

```
# create view by import_tag
view = client.create(target: 'view', 
                     name: 'myview', 
                     import_tag: 'test', 
                     strategy: 'import_tag',
                     desc: 'testview')
# create view by file with every line a sample uuid                     
view = client.create(target: 'view',
                     name: 'myview2',
                     strategy: 'file',
                     path: 'uuids.txt',
                     desc: 'testview')
                     
```

```
# create a general benchmark
benchmark = client.create(target: 'benchmark',
                          name: 'mybench',
                          strategy: 'general',
                          desc: 'no',
                          view: view,
                          class_count: 3,
                          sample_count: 1
                          )
# create allinner benchmark, allinner can also be **allinter** or **all**
benchmark = client.create(target: 'benchmark',
                          name: 'mybench',
                          strategy: 'allinner',
                          desc: 'no',
                          view: view,
                          )
# create allinner and oneinter benchmark, which means all genuine attemps is tested, and every class
# take one sample to do a inter-class match.
benchmark = client.create(target: 'benchmark',
                          name: 'mybench',
                          strategy: 'allInnerOneInter',
                          desc: 'no',
                          view: view,
                          )
# create benchmark using a file with every line 2 uuids.                          
benchmark = client.create(target: 'benchmark',
                          name: 'mybench',
                          strategy: 'file',
                          desc: 'no',
                          view: view,
                          path: 'benchmark.txt'
                          )
```

```
algorithm = client.create(target: 'algorithm', name: 'myalg', path: 'alg.zip', tag: 'tag1')
```

```
user = client.create(target: 'user', name: 'xianran', email: 'xianran@pku.edu.cn', password: '12345')
```

#### Delete Things

```
client.delete(target: 'benchmark', uuid: 'xxxxxxxxxx')
```

#### Run jobs

```
task = client.run(auuid: 'xxxxxxxx', buuid: 'yyyyyyyy')
loop do
  # Update the task info from server
  task = client.info(target: 'task', uuid: task.uuid)
  # Wait for the task to complete
  break if task.done == 1
end
```

#### Download things

You can download *task*, *benchmark*, *algorithm*, *images*

```
download(target: 'task', uuid: 'xxxxxxx', path: '/path/to/store/file')
download(target: 'benchmark', uuid: 'xxxxxxxxx', path: '/path/to/store/file)
download(target: 'algorithm', uuid: 'xxxxxxxxx', path: '/path/to/store/file)
# Below uuid is the uuid of the benchmark
download(target: 'image', uuid: 'xxxxxxxxx', path: '/path/to/store/file)
```