From 85d88e3905d6e0b027e47b8f5130f93d7c2b2b97 Mon Sep 17 00:00:00 2001 From: Luka Cehovin Zajc Date: Thu, 14 Mar 2024 14:44:16 +0100 Subject: [PATCH] Working on docs --- .readthedocs.yaml | 23 +++++++++++++++++++++++ docs/api.rst | 6 +++--- docs/api/analysis.rst | 6 +++--- docs/api/dataset.rst | 2 +- docs/api/{document.rst => report.rst} | 6 +++--- docs/conf.py | 7 ++++--- docs/index.rst | 4 ++-- docs/overview.rst | 10 +++++----- docs/requirements.txt | 4 ++++ vot/report/__init__.py | 14 ++++++++------ vot/report/html.py | 1 + 11 files changed, 57 insertions(+), 26 deletions(-) create mode 100644 .readthedocs.yaml rename docs/api/{document.rst => report.rst} (79%) create mode 100644 docs/requirements.txt diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000..e6b95af --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,23 @@ +# .readthedocs.yaml +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +# Set the version of Python and other tools you might need +build: + os: ubuntu-22.04 + tools: + python: "3.11" + +# Build documentation in the docs/ directory with Sphinx +sphinx: + configuration: docs/conf.py + +# We recommend specifying your dependencies to enable reproducible builds: +# https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html +python: + install: + - requirements: docs/requirements.txt + - requirements: requirements.txt \ No newline at end of file diff --git a/docs/api.rst b/docs/api.rst index 61f3434..ed7a80a 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -8,15 +8,15 @@ The API section contains the generated documentation of individual structures an api/analysis api/dataset - api/document + api/report api/experiment api/region api/stack api/tracker api/utilities -Core utilities --------------- +Configuration +------------- .. automodule:: vot :members: \ No newline at end of file diff --git a/docs/api/analysis.rst b/docs/api/analysis.rst index c29896a..96eb3ee 100644 --- a/docs/api/analysis.rst +++ b/docs/api/analysis.rst @@ -7,7 +7,7 @@ enables efficient execution of large-scale evaluations. .. automodule:: vot.analysis :members: -.. automodule:: vot.analysis.parallel +.. automodule:: vot.analysis.processor :members: Accuracy analysis @@ -19,7 +19,7 @@ Accuracy analysis Failure analysis ---------------- -.. automodule:: vot.analysis.failure +.. automodule:: vot.analysis.failures :members: Long-term measures @@ -37,5 +37,5 @@ Multi-start measures Supervision analysis -------------------- -.. automodule:: vot.analysis.supervision +.. automodule:: vot.analysis.supervised :members: \ No newline at end of file diff --git a/docs/api/dataset.rst b/docs/api/dataset.rst index bd34f02..a487bee 100644 --- a/docs/api/dataset.rst +++ b/docs/api/dataset.rst @@ -4,7 +4,7 @@ Dataset module .. automodule:: vot.dataset :members: -.. automodule:: vot.datase.common +.. automodule:: vot.dataset.common :members: Extended dataset support diff --git a/docs/api/document.rst b/docs/api/report.rst similarity index 79% rename from docs/api/document.rst rename to docs/api/report.rst index 2777d8b..8eb6941 100644 --- a/docs/api/document.rst +++ b/docs/api/report.rst @@ -1,5 +1,5 @@ Report module -============ +============= .. automodule:: vot.report :members: @@ -8,13 +8,13 @@ Report module :members: HTML report generation ------------------------- +---------------------- .. automodule:: vot.report :members: LaTeX report generation -------------------------- +----------------------- .. automodule:: vot.report.latex :members: diff --git a/docs/conf.py b/docs/conf.py index dbc9f00..7e23510 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -2,10 +2,11 @@ # import os import sys -sys.path.insert(0, os.path.abspath('../python')) +sys.path.insert(0, os.path.abspath('..')) # -- General configuration ------------------------------------------------ +print(sys.path) extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon'] @@ -24,7 +25,7 @@ # General information about the project. project = u'VOT Toolkit' -copyright = u'2022, Luka Cehovin Zajc' +copyright = u'2024, Luka Cehovin Zajc' author = u'Luka Cehovin Zajc' try: @@ -47,7 +48,7 @@ # # This is also used if you do content translation via gettext catalogs. # Usually you set "language" from the command line for these cases. -language = None +language = 'en' # There are two options for replacing |today|: either, you set today to some # non-false value, then it is used: diff --git a/docs/index.rst b/docs/index.rst index 58b2683..0e0bab8 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,14 +1,14 @@ Welcome to the VOT Toolkit documentation ======================================== -The VOT toolkit is the official evaluation tool for the [Visual Object Tracking (VOT) challenge](http://votchallenge.net/). +The VOT toolkit is the official evaluation tool for the `Visual Object Tracking (VOT) challenge `_. It is written in Python 3 language. The toolkit is designed to be easy to use and to have broad support for various trackers, datasets and evaluation measures. Contributions and development ----------------------------- -The VOT toolkit is developed by the VOT Committee, primarily by Luka Čehovin Zajc and the tracking community as an open-source project (GPLv3 license). +The VOT toolkit is developed by the VOT Committee, primarily by `Luka Čehovin Zajc `_ and the tracking community as an open-source project (GPLv3 license). Contributions to the VOT toolkit are welcome, the preferred way to do it is by submitting an issue or a pull requests on `GitHub `_. diff --git a/docs/overview.rst b/docs/overview.rst index ba24c58..d083d34 100644 --- a/docs/overview.rst +++ b/docs/overview.rst @@ -1,7 +1,7 @@ Overview ======== -The toolkit is designed as a modular framework with several modules that address different aspects of the performance evaluation problem. +The toolkit is organized as a modular collection of classes and methods with several modules that address different aspects of the performance evaluation problem. Key concepts ------------ @@ -15,27 +15,27 @@ Key concepts that are used throughout the toolkit are: * **Analysis** - an analysis is a set of **measures** that are used to evaluate the performance of a tracker (compare predicted trajectories to groundtruth). * **Stack** - a stack is a collection of **experiments** and **analyses** that are performed on a given dataset. * **Workspace** - a workspace is a collection of experiments and analyses that are performed on a given dataset. +* **Report** - a report is a representation of a list of analyses for a given experiment stack. Tracker support --------------- The toolkit supports various ways of interacting with a tracking methods. Primary manner (at the only supported at the moment) is using the TraX protocol. -The toolkit provides a wrapper for the TraX protocol that allows to use any tracker that supports the protocol. +The toolkit provides a wrapper for the TraX protocol that allows to use any tracker that supports the protocol. Other ways of interacting with a tracker can be added in the future. Dataset support --------------- -The toolkit is capable of using any dataset that is provided in the toolkit format. +The toolkit is capable of using any dataset that is provided in the official format or by registering a custom loaders. The toolkit format is a simple directory structure that contains a set of sequences. Each sequence is a directory that contains a set of frames and a groundtruth file. The groundtruth file is a text file that contains one line per frame. Each line contains the bounding box of the object in the frame in the format `x,y,w,h`. The toolkit format is used by the toolkit itself and by the VOT challenges. - Performance methodology support ------------------------------- Various performance measures and visualzatons are implemented, most of them were used in VOT challenges. * **Accuracy** - the accuracy measure is the overlap between the predicted and groundtruth bounding boxes. The overlap is measured using the intersection over union (IoU) measure. - * **Robustness** - the robustness measure is the number of failures of the tracker. A failure is defined as the overlap between the predicted and groundtruth bounding boxes being less than 0.5. + * **Robustness** - the robustness measure is the number of failures of the tracker. A failure is defined as the overlap between the predicted and groundtruth bounding boxes being less than a certain threshold. * **Expected Average Overlap** - the expected average overlap (EAO) is a measure that combines accuracy and robustness into a single measure. The EAO is computed as the area under the accuracy-robustness curve. * **Expected Overlap** - the expected overlap (EO) is a measure that combines accuracy and robustness into a single measure. The EO is computed as the area under the accuracy-robustness curve. diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..4608cbc --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,4 @@ +sphinx==5.3.0 +sphinx_rtd_theme==1.1.1 +readthedocs-sphinx-search==0.1.1 +recommonmark=0.7.1 \ No newline at end of file diff --git a/vot/report/__init__.py b/vot/report/__init__.py index 1490e79..fb5a59f 100644 --- a/vot/report/__init__.py +++ b/vot/report/__init__.py @@ -210,6 +210,7 @@ def __init__(self, identifier: str, frames: FrameList, trait=None): self._regions = {} def draw(self, frame, key, data): + """Draws the data on the frame.""" from vot.region import Region assert isinstance(data, Region) @@ -219,6 +220,7 @@ def draw(self, frame, key, data): self._regions[key][frame] = data def render(self, frame: int): + """Renders the frame and returns it as an array.""" from vot.utilities.draw import ImageDrawHandle assert frame >= 0 and frame < len(self) @@ -471,7 +473,7 @@ def make_figure(self, trait=None) -> typing.Tuple[Figure, Axes]: """ Makes the figure for the given trait. Args: - trait: The trait for which to make the figure. + trait (str): The trait for which to make the figure. Returns: A tuple containing the figure and the axes. @@ -519,13 +521,13 @@ class TrackerSorter(Attributee): analysis = String(default=None) result = Integer(val_min=0, default=0) - def __call__(self, experiments, trackers, sequences): + def __call__(self, experiments: typing.List["Experiment"], trackers: typing.List["Tracker"], sequences: typing.List["Sequence"]): """ Sorts the trackers. Arguments: - experiments (list of Experiment): The experiments. - trackers (list of Tracker): The trackers. - sequences (list of Sequence): The sequences. + experiments (typing.List[Experiment]): The experiments. + trackers (typing.List[Tracker]): The trackers. + sequences (typing.List[Sequence]): The sequences. Returns: A list of indices of the trackers in the sorted order. @@ -667,7 +669,7 @@ def generate_document(workspace: "Workspace", trackers: typing.List[Tracker], fo """Generate a report for a one or multiple trackers on an experiment stack and a set of sequences. Args: - workspace: The workspace to use for the report. + workspace (Workspace): The workspace to use for the report. trackers: The trackers to include in the report. format: The format of the report. name: The name of the report. diff --git a/vot/report/html.py b/vot/report/html.py index e0029a4..f32dd4f 100644 --- a/vot/report/html.py +++ b/vot/report/html.py @@ -122,6 +122,7 @@ def add_script(name, linked=False): # TODO: make table more general (now it assumes a tracker per row) def make_table(data: Table): + """Generates a table from a Table object.""" if len(data.header[2]) == 0: logger.debug("No measures found, skipping table") else: