From 129584b99e940b93411ce87b9ddad8b60ae284ff Mon Sep 17 00:00:00 2001
From: Timur Osmanov <54434686+TOsmanov@users.noreply.github.com>
Date: Thu, 20 Jan 2022 10:51:01 +0300
Subject: [PATCH] Update documentation. Update CLI section (#4056)
---
site/content/en/docs/manual/advanced/cli.md | 166 ++++++++++++++++++--
utils/cli/core/definition.py | 7 +-
2 files changed, 160 insertions(+), 13 deletions(-)
diff --git a/site/content/en/docs/manual/advanced/cli.md b/site/content/en/docs/manual/advanced/cli.md
index 99fe5e95..3cedb380 100644
--- a/site/content/en/docs/manual/advanced/cli.md
+++ b/site/content/en/docs/manual/advanced/cli.md
@@ -5,7 +5,8 @@ weight: 28
description: 'Guide to working with CVAT tasks in the command line interface. This section on [GitHub](https://github.com/openvinotoolkit/cvat/tree/develop/utils/cli).'
---
-**Description**
+## Description
+
A simple command line interface for working with CVAT tasks. At the moment it
implements a basic feature set but may serve as the starting point for a more
comprehensive CVAT administration tool in the future.
@@ -21,9 +22,20 @@ Overview of functionality:
- Export and download a whole task
- Import a task
-**Usage**
+## Usage
+
+To access the CLI, you need to have python in environment,
+as well as a clone of the CVAT repository and the necessary modules:
```bash
+git clone https://github.com/openvinotoolkit/cvat.git
+cd cvat/utils/cli
+pip install -r requirements.txt
+```
+
+You will get help with `cli.py`.
+
+```
usage: cli.py [-h] [--auth USER:[PASS]] [--server-host SERVER_HOST]
[--server-port SERVER_PORT] [--debug]
{create,delete,ls,frames,dump,upload,export,import} ...
@@ -46,13 +58,145 @@ optional arguments:
--debug show debug output
```
-**Examples**
+You can get help for each positional argument, e.g. `ls`:
+
+```bash
+cli.py ls -h
+```
+```
+usage: cli.py ls [-h] [--json]
+
+List all CVAT tasks in simple or JSON format.
+
+optional arguments:
+ -h, --help show this help message and exit
+ --json output JSON data
+```
+
+## Examples
+
+### Create
+
+Description of the options you can find in
+[Creating an annotation task](/docs/manual/basics/creating_an_annotation_task/) section.
+
+For create a task you need file contain labels in the `json` format, you can create a JSON label specification
+by using the [label constructor](/docs/manual/basics/creating_an_annotation_task/#labels).
+
+Example JSON labels file
+
+ ```json
+ [
+ {
+ "name": "cat",
+ "attributes": []
+ },
+ {
+ "name": "dog",
+ "attributes": []
+ }
+ ]
+ ```
+
+
+
+- Create a task named "new task" on the default server "localhost:8080", labels from the file "labels.json"
+ and local images "file1.jpg" and "file2.jpg", the task will be created as current user:
+ ```bash
+ cli.py create "new task" --labels labels.json local file1.jpg file2.jpg
+ ```
+- Create a task named "task 1" on the server "example.com" labels from the file "labels.json"
+ and local image "image1.jpg", the task will be created as user "user-1":
+ ```bash
+ cli.py --server-host example.com --auth user-1 create "task 1" \
+ --labels labels.json local image1.jpg
+ ```
+- Create a task named "task 1", labels from the project with id 1 and with a remote video file,
+ the task will be created as user "user-1":
+ ```bash
+ cli.py --auth user-1:password create "task 1" --project_id 1 \
+ remote https://github.com/opencv/opencv/blob/master/samples/data/vtest.avi?raw=true
+ ```
+- Create a task named "task 1 sort random", with labels "cat" and "dog", with chunk size 8,
+ with sorting-method random, frame step 10, copy the data on the CVAT server,
+ with use zip chunks and the video file will be taken from the shared resource:
+ ```bash
+ cli.py create "task 1 sort random" --labels '[{"name": "cat"},{"name": "dog"}]' --chunk_size 8 \
+ --sorting-method random --frame_step 10 --copy_data --use_zip_chunks share //share/dataset_1/video.avi
+ ```
+- Create a task named "task from dataset_1", labels from the file "labels.json", with link to bug tracker,
+ image quality will be reduced to 75, annotation in the format "CVAT 1.1" will be taken
+ from the file "annotation.xml", the data will be loaded from "dataset_1/images/",
+ the task will be created as user "user-2", and the password will need to be entered additionally:
+ ```bash
+ cli.py --auth user-2 create "task from dataset_1" --labels labels.json \
+ --bug_tracker https://bug-tracker.com/0001 --image_quality 75 --annotation_path annotation.xml \
+ --annotation_format "CVAT 1.1" local dataset_1/images/
+ ```
+- Create a task named "segmented task 1", labels from the file "labels.json", with overlay size 5,
+ segment size 100, with frames 5 through 705, using cache and with a remote video file:
+ ```bash
+ cli.py create "segmented task 1" --labels labels.json --overlap 5 --segment_size 100 \
+ --start_frame 5 --stop_frame 705 --use_cache \
+ remote https://github.com/opencv/opencv/blob/master/samples/data/vtest.avi?raw=true
+ ```
+- Create a task named "task 1 with sync annotation", with label "person",
+ with annotation storage in `git` repository, enable `lfs` and the image files from the shared resource:
+ ```bash
+ cli.py create "task 1 with sync annotation" --labels '[{"name": "person"}]' \
+ --dataset_repository_url https://github.com/user/dataset/blob/main/annotation/anno_file_name.zip \
+ --lfs share //share/large_dataset/images/
+ ```
+
+### Delete
+
+- Delete tasks with id "100", "101", "102" , the command will be executed from "user-1" having delete permissions:
+ ```bash
+ cli.py --auth user-1:password delete 100 101 102
+ ```
+
+### List
+
+- List all tasks:
+ ```bash
+ cli.py ls
+ ```
+- Save list of all tasks into file "list_of_tasks.json":
+ ```bash
+ cli.py ls --json > list_of_tasks.json
+ ```
+
+### Frames
+
+- Save frame 12, 15, 22 from task with id 119, into "images" folder with compressed quality:
+ ```bash
+ cli.py frames --outdir images --quality compressed 119 12 15 22
+ ```
+
+### Dump annotation
+
+- Dump annotation task with id 103, in the format `CVAT for images 1.1` and save to the file "output.xml":
+ ```bash
+ cli.py dump --format "CVAT for images 1.1" 103 output.xml
+ ```
+
+### Upload annotation
+
+- Upload annotation into task with id 105, in the format `CVAT 1.1` from the file "annotation.xml":
+ ```bash
+ cli.py upload --format "CVAT 1.1" 105 annotation.xml
+ ```
+
+### Export task
+
+- Export task with id 136 in the format `COCO 1.0` :
+ ```bash
+ cli.py export --format "COCO 1.0" 136
+ ```
+
+### Import
-- Create a task
- `cli.py create "new task" --labels labels.json local file1.jpg file2.jpg`
-- Delete some tasks
- `cli.py delete 100 101 102`
-- List all tasks
- `cli.py ls`
-- Dump annotations
- `cli.py dump --format "CVAT for images 1.1" 103 output.xml`
+- Import task from file "task_backup.zip" :
+ ```bash
+ cli.py import task_backup.zip
+ ```
diff --git a/utils/cli/core/definition.py b/utils/cli/core/definition.py
index b75c19fc..ca2a3c55 100644
--- a/utils/cli/core/definition.py
+++ b/utils/cli/core/definition.py
@@ -101,7 +101,10 @@ parser.add_argument(
task_create_parser = task_subparser.add_parser(
'create',
- description='Create a new CVAT task.'
+ description='''Create a new CVAT task. To create a task, you need
+ to specify labels using the --labels argument or
+ attach the task to an existing project using the
+ --project_id argument.'''
)
task_create_parser.add_argument(
'name',
@@ -380,7 +383,7 @@ export_task_parser.add_argument(
import_task_parser = task_subparser.add_parser(
'import',
- description='import a CVAT task.'
+ description='Import a CVAT task.'
)
import_task_parser.add_argument(
'filename',