Skip to content

Commit 70d3ae2

Browse files
willandfreewillandfree
committed
docs: add the documents to BasicSearch and SearchResult
1 parent edd5477 commit 70d3ae2

File tree

9 files changed

+377
-1
lines changed

9 files changed

+377
-1
lines changed

‎docs/code/basic_search.py‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
#!/usr/bin/env python3
2+
#
3+
# Copyright 2021 Graviti. Licensed under MIT License.
4+
#
5+
6+
# pylint: disable=wrong-import-position
7+
# pylint: disable=pointless-string-statement
8+
# pylint: disable=pointless-statement
9+
# pylint: disable=invalid-name
10+
# type: ignore[attr-defined]
11+
# https://github.com/python/mypy/issues/5858
12+
13+
"""This file includes the python code of basic_search.rst."""
14+
15+
"""Authorize a Dataset Client Instance"""
16+
from tensorbay import GAS
17+
18+
gas = GAS("<YOUR_ACCESSKEY>")
19+
dataset_client = gas.create_dataset("<DATASET_NAME>")
20+
21+
""""""
22+
23+
"""Create Job"""
24+
dataset_client.basic_search.create_job(
25+
title="search example",
26+
description="search description",
27+
conjunction="AND",
28+
unit="FILE",
29+
filters=[
30+
(
31+
"category",
32+
"in",
33+
[
34+
"human.pedestrian.adult",
35+
"human.pedestrian.child",
36+
"human.pedestrian.construction_worker",
37+
],
38+
"BOX3D",
39+
),
40+
("size", ">", 0),
41+
("withLabel", "=", True),
42+
("attribute", "in", {"attribute_1": [True, False], "attribute_2": [1, 2]}, "BOX3D"),
43+
],
44+
)
45+
""""""
46+
47+
"""Get and List"""
48+
job = dataset_client.basic_search.get_job("jobId")
49+
job = dataset_client.basic_search.list_jobs()[0]
50+
""""""
51+
52+
"""Get Job Info"""
53+
job.status
54+
job.result
55+
job.error_message
56+
job.arguments
57+
""""""
58+
59+
"""Update Job"""
60+
job.update()
61+
job.update(until_complete=True)
62+
""""""
63+
64+
"""Abort and Retry Job"""
65+
job.abort()
66+
job.retry()
67+
""""""

‎docs/code/search_result.py‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
#!/usr/bin/env python3
2+
#
3+
# Copyright 2021 Graviti. Licensed under MIT License.
4+
#
5+
6+
# pylint: disable=wrong-import-position
7+
# pylint: disable=pointless-string-statement
8+
# pylint: disable=pointless-statement
9+
# pylint: disable=invalid-name
10+
# type: ignore[attr-defined]
11+
# https://github.com/python/mypy/issues/5858
12+
13+
"""This file includes the python code of search_result.rst."""
14+
15+
"""Obtain a SearchResult Instance"""
16+
from tensorbay import GAS
17+
18+
gas = GAS("<YOUR_ACCESSKEY>")
19+
dataset_client = gas.get_dataset("<DATASET_NAME>")
20+
21+
job = dataset_client.basic_search.create_job(
22+
title="search example",
23+
description="search description",
24+
conjunction="AND",
25+
unit="FILE",
26+
filters=[
27+
(
28+
"category",
29+
"in",
30+
[
31+
"human.pedestrian.adult",
32+
"human.pedestrian.child",
33+
"human.pedestrian.construction_worker",
34+
],
35+
"BOX3D",
36+
),
37+
("size", ">", 0),
38+
("withLabel", "=", True),
39+
("attribute", "in", {"attribute_1": [True, False], "attribute_2": [1, 2]}, "BOX3D"),
40+
],
41+
)
42+
search_result = job.result
43+
""""""
44+
45+
"""Get SearchResult Info"""
46+
search_result.job_id
47+
search_result.search_result_id
48+
""""""
49+
50+
"""Get Label Statistics"""
51+
search_result.get_label_statistics()
52+
""""""
53+
54+
"""List Segment names"""
55+
search_result.list_segment_names()
56+
""""""
57+
58+
"""List Data"""
59+
search_result.list_data(segment_name="<SEGMENT_NAME>")
60+
""""""
61+
62+
"""Obtain a FusionSearchResult Instance"""
63+
fusion_dataset_client = gas.get_dataset("<DATASET_NAME>", is_fusion=True)
64+
65+
job = dataset_client.basic_search.create_job(
66+
title="search example",
67+
description="search description",
68+
conjunction="AND",
69+
unit="Frame",
70+
filters=[
71+
("sensor", "in", ["CAM_BACK_RIGHT", "CAM_FRONT"]),
72+
("size", ">", 0),
73+
("withLabel", "=", True),
74+
("attribute", "in", {"attribute_1": [True, False], "attribute_2": [1, 2]}, "BOX3D"),
75+
],
76+
)
77+
fusion_search_result = job.result
78+
""""""
79+
80+
"""The same function as SearchResult"""
81+
fusion_search_result.job_id
82+
fusion_search_result.search_result_id
83+
84+
fusion_search_result.get_label_statistics()
85+
86+
fusion_search_result.list_segment_names()
87+
""""""
88+
89+
"""List Frames"""
90+
fusion_search_result.list_frames(segment_name="<SEGMENT_NAME>")
91+
""""""
92+
93+
"""Get Sensors"""
94+
fusion_search_result.get_sensors(segment_name="<SEGMENT_NAME>")
95+
""""""

‎docs/source/features/search/basic_search.rst‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
..
2+
Copyright 2021 Graviti. Licensed under MIT License.
3+
4+
##############
5+
Basic Search
6+
##############
7+
8+
TensorBay supports basic search based on different commits.
9+
10+
.. literalinclude:: ../../../../docs/code/basic_search.py
11+
:language: python
12+
:start-after: """Authorize a Dataset Client Instance"""
13+
:end-before: """"""
14+
15+
****************
16+
BasicSearchJob
17+
****************
18+
19+
TensorBay SDK allows create, get or list :class:`~tensorbay.client.job.BasicSearchJob` via :class:`~tensorbay.client.version.BasicSearch`.
20+
21+
Create
22+
======
23+
24+
A BasicSearchJob can be created by :func:`~tensorbay.client.version.BasicSearch.create_job`
25+
26+
.. literalinclude:: ../../../../docs/code/basic_search.py
27+
:language: python
28+
:start-after: """Create Job"""
29+
:end-before: """"""
30+
31+
.. note::
32+
#. conjunction
33+
The logical conjunction between search filters, which includes "AND" and "OR".
34+
#. unit
35+
The unit of basic search. There are two options:
36+
* "FILE": Get the data that meets search filters;
37+
* "FRAME": If at least one data in a frame meets search filters, all data in the frame will be get. This option only works on fusion dataset.
38+
#. filters
39+
The list of basic search criteria whose format is (key, operator, value, label_type).
40+
* "key": The factor for filtering, is a member of ["segment", "size", "withLabel", "frame", "sensor", "category", "attribute", "dataRemotePath"].
41+
* "operator": The operation for filtering, is a member of ["like", "in", "=", ">", "<", ">=", "<="].
42+
* "value": Reference value for filtering.
43+
* "label_type"：The label type it belongs to when filtering by category and attribute.
44+
There are also some limits on operations of specific factor, and it lists as following:
45+
================== ===========================
46+
key permitted operator
47+
================== ===========================
48+
"segment" "in"
49+
"size" "=", ">", "<", ">=", "<="
50+
"withLabel" "="
51+
"frame" "like", "="
52+
"sensor" "in"
53+
"category" "in"
54+
"attribute" "in"
55+
"dataRemotePath" "like", "="
56+
================== ===========================
57+
58+
Get or list
59+
===========
60+
61+
The latest BasicSearchJob can be obtained by :func:`~tensorbay.client.version.BasicSearch.get_job` or :func:`~tensorbay.client.version.BasicSearch.list_jobs`.
62+
63+
.. literalinclude:: ../../../../docs/code/basic_search.py
64+
:language: python
65+
:start-after: """Get and List"""
66+
:end-before: """"""
67+
68+
Get information
69+
===============
70+
71+
Available BasicSearchJob information includes ``title``, ``description``, ``job_id``, ``arguments``, ``created_at``, ``started_at``, ``finished_at``,
72+
``status``, ``error_message`` and ``result``.
73+
74+
.. literalinclude:: ../../../../docs/code/basic_search.py
75+
:language: python
76+
:start-after: """Get Job Info"""
77+
:end-before: """"""
78+
79+
.. note::
80+
If the BasicSearchJob is successfully completed, the result will be :class:`~tensorbay.client.search.SearchResult` or :class:`~tensorbay.client.search.FusionSearchResult`.
81+
See more details in :doc:`/features/search/search_result`.
82+
83+
.. important::
84+
Only the latest five search results for one dataset can be used.
85+
86+
Update
87+
======
88+
89+
The latest information of a BasicSearchJob can be obtained after :func:`~tensorbay.client.job.Job.update`. Note that if the ``until_complete`` is
90+
set to ``True``, the BasicSearchJob will be blocked until it is completed.
91+
92+
.. literalinclude:: ../../../../docs/code/basic_search.py
93+
:language: python
94+
:start-after: """Update Job"""
95+
:end-before: """"""
96+
97+
Abort or retry
98+
==============
99+
100+
BasicSearchJob also supports :func:`~tensorbay.client.job.Job.abort` and :func:`~tensorbay.client.job.Job.retry`:
101+
102+
.. literalinclude:: ../../../../docs/code/basic_search.py
103+
:language: python
104+
:start-after: """Abort and Retry Job"""
105+
:end-before: """"""

‎docs/source/features/search/index.rst‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
..
2+
Copyright 2021 Graviti. Licensed under MIT License.
3+
4+
########
5+
Search
6+
########
7+
8+
TensorBay supports dataset search.
9+
10+
11+
.. toctree::
12+
:maxdepth: 1
13+
14+
basic_search
15+
search_result

‎docs/source/features/search/search_result.rst‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
..
2+
Copyright 2021 Graviti. Licensed under MIT License.
3+
4+
##############
5+
SearchResult
6+
##############
7+
8+
TensorBay SDK allows create :class:`~tensorbay.client.search.SearchResult` via :class:`~tensorbay.client.job.BasicSearchJob`.
9+
10+
.. literalinclude:: ../../../../docs/code/search_result.py
11+
:language: python
12+
:start-after: """Obtain a SearchResult Instance"""
13+
:end-before: """"""
14+
15+
Get label statistics
16+
====================
17+
18+
The label statistics of the search result can be obtained by :func:`~tensorbay.client.search.SearchResult.get_label_statistics`
19+
20+
.. literalinclude:: ../../../../docs/code/search_result.py
21+
:language: python
22+
:start-after: """Get Label Statistics"""
23+
:end-before: """"""
24+
25+
List segment names
26+
==================
27+
28+
All segment names can be obtained by :func:`~tensorbay.client.search.SearchResult.list_segment_names`
29+
30+
.. literalinclude:: ../../../../docs/code/search_result.py
31+
:language: python
32+
:start-after: """List Segment names"""
33+
:end-before: """"""
34+
35+
List Data
36+
=========
37+
38+
Required data of the specific segment can be obtained by :func:`~tensorbay.client.search.SearchResult.list_data`
39+
40+
.. literalinclude:: ../../../../docs/code/search_result.py
41+
:language: python
42+
:start-after: """List Data"""
43+
:end-before: """"""
44+
45+
46+
********************
47+
FusionSearchResult
48+
********************
49+
50+
TensorBay SDK allows create :class:`~tensorbay.client.search.FusionSearchResult` via :class:`~tensorbay.client.job.BasicSearchJob`.
51+
52+
.. literalinclude:: ../../../../docs/code/search_result.py
53+
:language: python
54+
:start-after: """Obtain a FusionSearchResult Instance"""
55+
:end-before: """"""
56+
57+
FusionSearchResult can also get label statistics and list segment names in the same way as searchResult.
58+
59+
.. literalinclude:: ../../../../docs/code/search_result.py
60+
:language: python
61+
:start-after: """The same function as SearchResult"""
62+
:end-before: """"""
63+
64+
65+
List frames
66+
===========
67+
68+
Required frames of the specific segment can be obtained by :func:`~tensorbay.client.search.FusionSearchResult.list_frames`
69+
70+
.. literalinclude:: ../../../../docs/code/search_result.py
71+
:language: python
72+
:start-after: """List Frames"""
73+
:end-before: """"""
74+
75+
Get Sensors
76+
===========
77+
78+
The sensors of the specific segment can be obtained by :func:`~tensorbay.client.search.FusionSearchResult.get_sensors`
79+
80+
.. literalinclude:: ../../../../docs/code/search_result.py
81+
:language: python
82+
:start-after: """Get Sensors"""
83+
:end-before: """"""

‎docs/source/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,7 @@ It provides:
4747
features/dataset_management
4848
features/version_control/index
4949
features/visualization
50+
features/search/index
5051

5152
.. toctree::
5253
:maxdepth: 1

‎docs/source/reference/api/client/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,3 +21,4 @@ tensorbay.client
2121
profile
2222
statistics
2323
job
24+
search

‎docs/source/reference/api/client/search.rst‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
..
2+
Copyright 2021 Graviti. Licensed under MIT License.
3+
4+
tensorbay.client.search
5+
========================
6+
7+
.. automodule:: tensorbay.client.search
8+
:members:
9+
:show-inheritance:

0 commit comments

Comments
 (0)