Skip to content

Commit c7d1cd4

Browse files
ktro2828ktro2828
authored
docs: update CLI documentation (#159)
* docs: add example results of t4sanity Signed-off-by: ktro2828 <kotaro.uetake@tier4.jp> * docs: update document for CLI Signed-off-by: ktro2828 <kotaro.uetake@tier4.jp> --------- Signed-off-by: ktro2828 <kotaro.uetake@tier4.jp>
1 parent ca9a913 commit c7d1cd4

7 files changed

Lines changed: 179 additions & 153 deletions

File tree

‎docs/tutorials/cli.md‎

Lines changed: 0 additions & 146 deletions
This file was deleted.

‎docs/tutorials/cli/index.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
## CLI Support
2+
3+
Following command line tools are supported:
4+
5+
- [`t4viz`: Visualize T4 dataset features](./t4viz.md)
6+
- [`t4sanity`: Sanity checker of T4 dataset](./t4sanity.md)

‎docs/tutorials/cli/t4sanity.md‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
`t4sanity` performs sanity checks on T4 datasets, reporting any issues in a structured format.
2+
It checks the dataset directories and versions, tries to load them using the `Tier4` library, and reports any exceptions or warnings.
3+
4+
```shell
5+
$ t4sanity -h
6+
7+
Usage: t4sanity [OPTIONS] DB_PARENT
8+
9+
╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────────────────────────╮
10+
│ * db_parent TEXT Path to parent directory of the databases [default: None] [required] │
11+
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
12+
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
13+
│ --version -v Show the application version and exit. │
14+
│ --include-warning -iw Indicates whether to report any warnings. │
15+
│ --install-completion Install completion for the current shell. │
16+
│ --show-completion Show completion for the current shell, to copy it or customize the installation. │
17+
│ --help -h Show this message and exit. │
18+
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
19+
```
20+
21+
## Shell Completion
22+
23+
Run the following command to install completion, and reload shell.
24+
25+
```{ .shell .copy }
26+
t4sanity --install-completion
27+
```
28+
29+
## Usages
30+
31+
As an example, we have the following the dataset structure:
32+
33+
```shell
34+
<DATA_ROOT>
35+
├── dataset1
36+
│ └── <VERSION>
37+
│ ├── annotation
38+
│ ├── data
39+
| ...
40+
├── dataset2
41+
│ ├── annotation
42+
│ ├── data
43+
| ...
44+
...
45+
```
46+
47+
### Exclude Warnings
48+
49+
To run sanity check ignoring warnings, providing the path to the parent directory of the datasets:
50+
51+
```shell
52+
$ t4sanity <DATA_ROOT>
53+
54+
>>> Sanity checking...: 97it [00:03, 26.60it/s]
55+
+--------------------------------------+---------+------------------------------------------------------------------------------------------------+
56+
| DatasetID | Version | Message |
57+
+--------------------------------------+---------+------------------------------------------------------------------------------------------------+
58+
| 96200480-ae59-44cb-9e4e-dd9021e250e8 | 2 | bbox must be (xmin, ymin, xmax, ymax) and xmin <= xmax && ymin <= ymax: (1671, 198, 1440, 229) |
59+
| ca346afb-ea1a-4c5c-8117-544bd9ff6aca | 2 | bbox must be (xmin, ymin, xmax, ymax) and xmin <= xmax && ymin <= ymax: (1793, 99, 1440, 222) |
60+
...
61+
```
62+
63+
### Include Warnings
64+
65+
To run sanity check and report any warnings, use the `-iw; --include-warning` option:
66+
67+
```shell
68+
$ t4sanity <DATA_ROOT> -iw
69+
70+
>>> Sanity checking...: 97it [00:03, 29.31it/s]
71+
+--------------------------------------+---------+------------------------------------------------------------------------------------------------+
72+
| DatasetID | Version | Message |
73+
+--------------------------------------+---------+------------------------------------------------------------------------------------------------+
74+
| 96200480-ae59-44cb-9e4e-dd9021e250e8 | 2 | bbox must be (xmin, ymin, xmax, ymax) and xmin <= xmax && ymin <= ymax: (1671, 198, 1440, 229) |
75+
| ca346afb-ea1a-4c5c-8117-544bd9ff6aca | 2 | bbox must be (xmin, ymin, xmax, ymax) and xmin <= xmax && ymin <= ymax: (1793, 99, 1440, 222) |
76+
| ed96b707-e7f4-4a71-9e6b-571ffd56c4c4 | 2 | level: Not available is not supported, Visibility.UNAVAILABLE will be assigned. |
77+
...
78+
```

‎docs/tutorials/cli/t4viz.md‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
`t4viz` performs visualizing particular dataset attributes from command line.
2+
3+
```shell
4+
$ t4viz -h
5+
6+
Usage: t4viz [OPTIONS] COMMAND [ARGS]...
7+
8+
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────╮
9+
│ --version -v Show the application version and exit. │
10+
│ --install-completion Install completion for the current shell. │
11+
│ --show-completion Show completion for the current shell, to copy it or customize the installation. │
12+
│ --help -h Show this message and exit. │
13+
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
14+
╭─ Commands ───────────────────────────────────────────────────────────────────────────────────────────────────────╮
15+
│ scene Visualize a specific scene. │
16+
│ instance Visualize a particular instance in the corresponding scene. │
17+
│ pointcloud Visualize pointcloud in the corresponding scene. │
18+
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
19+
```
20+
21+
## Shell Completion
22+
23+
Run the following command to install completion, and reload shell.
24+
25+
```{ .shell .copy }
26+
t4viz --install-completion
27+
```
28+
29+
## Usages
30+
31+
### Scene
32+
33+
This command performs the same behavior with [`Tier4.render_scene(...)`](../render.md#rendering-scene).
34+
35+
For options, run `t4viz scene -h`.
36+
37+
```shell
38+
t4viz scene <DATA_ROOT> [OPTIONS]
39+
```
40+
41+
### Specific Instance(s)
42+
43+
This command performs the same behavior with [`Tier4.render_instance(...)`](../render.md#rendering-instances).
44+
45+
For options, run `t4viz instance -h`.
46+
47+
```shell
48+
t4viz instance <DATA_ROOT> <INSTANCE_TOKEN> [OPTIONS]
49+
```
50+
51+
You can also specify multiple instance tokens:
52+
53+
```shell
54+
t4viz instance <DATA_ROOT> <INSTANCE_TOKEN1> <INSTANCE_TOKEN2> ... [OPTIONS]
55+
```
56+
57+
### PointCloud
58+
59+
This command performs the same behavior with [`Tier4.render_pointcloud(...)`](../render.md#rendering-pointcloud).
60+
61+
For options, run `t4viz pointcloud -h`.
62+
63+
```shell
64+
t4viz pointcloud <DATA_ROOT> [OPTIONS]
65+
```
66+
67+
### Future Trajectories
68+
69+
`scene` and `instance` commands support visualizing future trajectories for each object.
70+
71+
By specifying `-f [--future]` option, you can render them in the particular time length:
72+
73+
```shell
74+
t4viz <COMMAND> ... -f <FUTURE_LENGTH[s]>
75+
```
76+
77+
### Save Recording as `.rrd`
78+
79+
You can save visualized recording with `-o [--output]` option as follows:
80+
81+
```shell
82+
t4viz <COMMAND> ... -o <OUTPUT_DIR>
83+
```
84+
85+
Note that if you specify `--output` option, viewer will not be spawned.

‎docs/tutorials/customize.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
## Generate Schema Record with a New Token
1+
## Generate with a New Token
22

33
---
44

@@ -28,7 +28,7 @@ Attribute(token='b08701e5095fbd12a45e7f51b85ffc08', name='foo', description='thi
2828
Attribute(token='f40e605870aa29b1473ca6e65255c45e', name='foo', description='this is re-generated attribute.')
2929
```
3030

31-
## Customize Schema Class
31+
## Customize Schema Classes
3232

3333
---
3434

‎docs/tutorials/render.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
If you want to visualize annotation results, `Tier4` supports some rendering methods as below.
44

5-
### Rendering Scene
5+
### Scene
66

77
```python
88
>>> scene_token = t4.scene[0].token
@@ -11,7 +11,7 @@ If you want to visualize annotation results, `Tier4` supports some rendering met
1111

1212
![Render Scene GIF](../assets/render_scene.gif)
1313

14-
### Rendering Instance(s)
14+
### Specific Instance(s)
1515

1616
```python
1717
>>> instance_token = t4.instance[0].token
@@ -27,7 +27,7 @@ You can also render multiple instances at once:
2727
>>> t4.render_instance(instance_tokens)
2828
```
2929

30-
### Rendering PointCloud
30+
### PointCloud
3131

3232
```python
3333
>>> scene_token = t4.scene[0].token

‎mkdocs.yaml‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,8 +9,11 @@ nav:
99
- Tutorials:
1010
- Initialization: tutorials/initialize.md
1111
- Visualization: tutorials/render.md
12-
- Customization: tutorials/customize.md
13-
- CLI: tutorials/cli.md
12+
- Schema Customization: tutorials/customize.md
13+
- CLI:
14+
- Command Line Tools: tutorials/cli/index.md
15+
- t4viz: tutorials/cli/t4viz.md
16+
- t4sanity: tutorials/cli/t4sanity.md
1417
- API References:
1518
- t4_devkit.tier4: apis/tier4.md
1619
- t4_devkit.helper: apis/helper.md

0 commit comments

Comments
 (0)