Skip to content

Commit

Permalink
update readme (#128)
Browse files Browse the repository at this point in the history
  • Loading branch information
almazan authored Nov 23, 2020
1 parent 3eca396 commit e07d9c7
Showing 1 changed file with 20 additions and 20 deletions.
40 changes: 20 additions & 20 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
# Darwin
Official library to manage datasets along with
Official library to manage datasets along with
[V7 Darwin annotation platform](https://darwin.v7labs.com).

Darwin-py can both be used from the [command line](#usage-as-a-command-line-interface-cli) and as a [python library](#usage-as-a-python-library).
Expand All @@ -10,9 +10,9 @@ Main functions are (but not limited to):
- Listing local and remote datasets
- Create/remove datasets
- Upload/download data to/from remote datasets
- Direct integration with pytorch dataloaders (See [torch/README.md](darwin/torch/README.md))
- Direct integration with PyTorch dataloaders

Support tested for python 3.7.
Support tested for python 3.8.

## Installation

Expand All @@ -27,33 +27,33 @@ You can now type `darwin` in your terminal and access the command line interface
## Usage as a Command Line Interface (CLI)

Once installed, `darwin` is accessible as a command line tool.
A useful way to navigate the CLI usage is through the help command `-h/--help` which will
provide additional information for each command available.
A useful way to navigate the CLI usage is through the help command `-h/--help` which will
provide additional information for each command available.


### Client Authentication
### Client Authentication

To perform remote operations on Darwin you first need to authenticate.
This requires a [team-specific API-key](https://darwin.v7labs.com/?settings=api-keys).
This requires a [team-specific API-key](https://darwin.v7labs.com/?settings=api-keys).
If you do not already have a Darwin account, you can [contact us](https://www.v7labs.com/contact) and we can set one up for you.

To start the authentication process:

```
$ darwin authenticate
API key:
API key:
Make example-team the default team? [y/N] y
Datasets directory [~/.darwin/datasets]:
Datasets directory [~/.darwin/datasets]:
Authentication succeeded.
```

You will be then prompted to enter your API-key, whether you want to set the corresponding team as
You will be then prompted to enter your API-key, whether you want to set the corresponding team as
default and finally the desired location on the local file system for the datasets of that team.
This process will create a configuration file at `~/.darwin/config.yaml`.
This file will be updated with future authentications for different teams.


### Listing local and remote datasets
### Listing local and remote datasets

Lists a summary of local existing datasets
```
Expand All @@ -71,15 +71,15 @@ example-team/mydataset 112025 73.0%
```


### Create/remove a dataset
### Create/remove a dataset

To create an empty dataset remotely:

```
$ darwin dataset create test
Dataset 'test' (example-team/test) has been created.
Access at https://darwin.v7labs.com/datasets/579
```
```

The dataset will be created in the team you're authenticated for.

Expand All @@ -91,13 +91,13 @@ Do you want to continue? [y/N] y
```


### Upload/download data to/from a remote dataset
### Upload/download data to/from a remote dataset

Uploads data to an existing remote project.
It takes the dataset name and a single image (or directory) with images/videos to upload as
parameters.
It takes the dataset name and a single image (or directory) with images/videos to upload as
parameters.

The `-e/--exclude` argument allows to indicate file extension/s to be ignored from the data_dir.
The `-e/--exclude` argument allows to indicate file extension/s to be ignored from the data_dir.
e.g.: `-e .jpg`

For videos, the frame rate extraction rate can be specified by adding `--fps <frame_rate>`
Expand All @@ -108,7 +108,7 @@ Supported extensions:

```
$ darwin dataset push test /path/to/folder/with/images
100%|████████████████████████| 2/2 [00:01<00:00, 1.27it/s]
100%|████████████████████████| 2/2 [00:01<00:00, 1.27it/s]
```

Before a dataset can be downloaded, a release needs to be generated:
Expand Down Expand Up @@ -140,7 +140,7 @@ Dataset example-team/test:0.1 downloaded at /directory/choosen/at/authentication

The framework is designed to be usable as a standalone python library.
Usage can be inferred from looking at the operations performed in `darwin/cli_functions.py`.
A minimal example to download a dataset is provided below and a more extensive one can be found in
A minimal example to download a dataset is provided below and a more extensive one can be found in
[darwin_demo.py](./darwin_demo.py).

```python
Expand All @@ -152,4 +152,4 @@ dataset.pull() # downloads annotations and images for the latest exported versio
```


See [torch/README.md](darwin/torch/README.md) for how to integrate darwin datasets directly in torch.
Follow [this guide](https://docs.v7labs.com/docs/loading-a-dataset-in-python) for how to integrate darwin datasets directly in PyTorch.

0 comments on commit e07d9c7

Please sign in to comment.