diff --git a/docs/code/VOC2012Segmentation.py b/docs/code/VOC2012Segmentation.py new file mode 100644 index 000000000..5ff55f8bb --- /dev/null +++ b/docs/code/VOC2012Segmentation.py @@ -0,0 +1,76 @@ +#!/usr/bin/env python3 +# +# Copyright 2021 Graviti. Licensed under MIT License. +# + +# pylint: disable=wrong-import-position +# pylint: disable=wrong-import-order +# pylint: disable=not-callable +# pylint: disable=ungrouped-imports +# pylint: disable=import-error +# pylint: disable=pointless-string-statement +# pylint: disable=invalid-name +# pylint: disable=unused-import +# flake8: noqa: F401 +# type: ignore[attr-defined] + +"""This file includes the python code of VOC2012Segmentation.rst.""" + +"""Authorize a Client Instance""" +from tensorbay import GAS + +ACCESS_KEY = "Accesskey-*****" +gas = GAS(ACCESS_KEY) +"""""" + +"""Create Dataset""" +gas.create_dataset("VOC2012Segmentation") +"""""" + +"""Organize Dataset / regular import""" +from tensorbay.dataset import Data, Dataset +from tensorbay.label import InstanceMask, SemanticMask + +"""""" + +"""Organize dataset / import dataloader""" +from tensorbay.opendataset import VOC2012Segmentation + +dataset = VOC2012Segmentation("path/to/dataset/directory") +"""""" + +"""Upload Dataset""" +dataset_client = gas.upload_dataset(dataset, jobs=8) +dataset_client.commit("initial commit") +"""""" + +"""Read Dataset / get dataset""" +dataset = Dataset("VOC2012Segmentation", gas) +"""""" + +"""Read Dataset / get segment""" +segment = dataset[0] +"""""" + +"""Read Dataset / get data""" +data = segment[0] +"""""" + +"""Read Dataset / get label""" +try: + from PIL import Image +except ModuleNotFoundError: + from tensorbay.opendataset._utility.mocker import Image + +label_semantic_mask = data.label.semantic_mask +semantic_all_attributes = label_semantic_mask.all_attributes +semantic_mask = Image.open(label_semantic_mask.open()) +semantic_mask.show() +label_instance_mask = data.label.instance_mask +instance_all_attributes = label_instance_mask.all_attributes +instance_mask_url = label_instance_mask.get_url() +"""""" + +"""Delete Dataset""" +gas.delete_dataset("VOC2012Segmentation") +"""""" diff --git a/docs/source/examples/VOC2012Segmentation.rst b/docs/source/examples/VOC2012Segmentation.rst new file mode 100644 index 000000000..78a4a003d --- /dev/null +++ b/docs/source/examples/VOC2012Segmentation.rst @@ -0,0 +1,193 @@ +###################### + VOC2012 Segmentation +###################### + +This topic describes how to manage the `VOC2012 Segmentation dataset`_, +which is a dataset with :ref:`reference/label_format/SemanticMask:SemanticMask` +and :ref:`reference/label_format/InstanceMask:InstanceMask` labels +(:numref:`Fig. %s ` and :numref:`Fig. %s `). + +.. _VOC2012 Segmentation dataset: https://gas.graviti.cn/dataset/hello-dataset/VOC2012Segmentation + +.. _example-semantic-mask: + +.. figure:: ../images/example-semanticmask.png + :scale: 150 % + :align: center + + The preview of a semantic mask from "VOC2012 Segmentation". + +.. _example-instance-mask: + +.. figure:: ../images/example-instancemask.png + :scale: 150 % + :align: center + + The preview of a instance mask from "VOC2012 Segmentation". + + +***************************** + Authorize a Client Instance +***************************** + +An :ref:`reference/glossary:accesskey` is needed to authenticate identity when using TensorBay. + +.. literalinclude:: ../../../docs/code/VOC2012Segmentation.py + :language: python + :start-after: """Authorize a Client Instance""" + :end-before: """""" + +**************** + Create Dataset +**************** + + +.. literalinclude:: ../../../docs/code/VOC2012Segmentation.py + :language: python + :start-after: """Create Dataset""" + :end-before: """""" + +****************** + Organize Dataset +****************** + +It takes the following steps to organize "VOC2012 Segmentation" dataset by the :class:`~tensorbay.dataset.dataset.Dataset` instance. + +Step 1: Write the Catalog +========================= + +A :ref:`Catalog ` contains all label information of one dataset, +which is typically stored in a json file. + +.. literalinclude:: ../../../tensorbay/opendataset/VOC2012Segmentation/catalog.json + :language: json + :name: voc2012segmentation-catalog + :linenos: + +The annotation types for "VOC2012 Segmentation" are :ref:`reference/label_format/SemanticMask:SemanticMask` +and :ref:`reference/label_format/InstanceMask:InstanceMask`, and there are 22 +:ref:`reference/label_format/CommonLabelProperties:Category` types for :ref:`reference/label_format/SemanticMask:SemanticMask`. There are 2 +:ref:`reference/label_format/CommonLabelProperties:Category` types for :ref:`reference/label_format/InstanceMask:InstanceMask`, category 0 represents the +background, and category 255 represents the border of instances. + +.. important:: + + See :ref:`catalog table ` for more catalogs with different label types. + +Step 2: Write the Dataloader +============================ + +A :ref:`reference/glossary:dataloader` is needed to organize the dataset into +a :class:`~tensorbay.dataset.dataset.Dataset` instance. + +.. literalinclude:: ../../../tensorbay/opendataset/VOC2012Segmentation/loader.py + :language: python + :name: voc2012segmentation-dataloader + :linenos: + +See :ref:`SemanticMask annotation ` +and :ref:`InstanceMask annotation ` for more details. + +.. note:: + + Since the :ref:`VOC2012 Segmentation dataloader ` above is already included in + TensorBay, so it uses relative import. + However, the regular import should be used when writing a new dataloader. + +.. literalinclude:: ../../../docs/code/VOC2012Segmentation.py + :language: python + :start-after: """Organize Dataset / regular import""" + :end-at: from tensorbay.label import InstanceMask, SemanticMask + +There are already a number of dataloaders in TensorBay SDK provided by the community. +Thus, instead of writing, importing an available dataloader is also feasible. + +.. literalinclude:: ../../../docs/code/VOC2012Segmentation.py + :language: python + :start-after: """Organize dataset / import dataloader""" + :end-before: """""" + +.. note:: + + Note that catalogs are automatically loaded in available dataloaders, users do not have to write them again. + +.. important:: + + See :ref:`dataloader table ` for dataloaders with different label types. + +******************* + Visualize Dataset +******************* + +Optionally, the organized dataset can be visualized by **Pharos**, which is a TensorBay SDK plug-in. +This step can help users to check whether the dataset is correctly organized. +Please see :ref:`features/visualization:Visualization` for more details. + +**************** + Upload Dataset +**************** + +The organized "VOC2012 Segmentation" dataset can be uploaded to tensorBay for sharing, reuse, etc. + +.. literalinclude:: ../../../docs/code/VOC2012Segmentation.py + :language: python + :start-after: """Upload Dataset""" + :end-before: """""" + +Similar with Git, the commit step after uploading can record changes to the dataset as a version. +If needed, do the modifications and commit again. +Please see :ref:`features/version_control:Version Control` for more details. + +************** + Read Dataset +************** + +Now "VOC2012 Segmentation" dataset can be read from TensorBay. + +.. literalinclude:: ../../../docs/code/VOC2012Segmentation.py + :language: python + :start-after: """Read Dataset / get dataset""" + :end-before: """""" + +In :ref:`reference/dataset_structure:Dataset` "VOC2012 Segmentation", there are two +:ref:`segments `: ``train`` and ``val``. +Get a segment by passing the required segment name or the index. + +.. literalinclude:: ../../../docs/code/VOC2012Segmentation.py + :language: python + :start-after: """Read Dataset / get segment""" + :end-before: """""" + +In the ``train`` :ref:`reference/dataset_structure:Segment`, +there is a sequence of :ref:`reference/dataset_structure:Data`, +which can be obtained by index. + +.. literalinclude:: ../../../docs/code/VOC2012Segmentation.py + :language: python + :start-after: """Read Dataset / get data""" + :end-before: """""" + +In each :ref:`reference/dataset_structure:Data`, +there are one :ref:`reference/label_format/SemanticMask:SemanticMask` annotation and one :ref:`reference/label_format/InstanceMask:InstanceMask` annotation. + +.. literalinclude:: ../../../docs/code/VOC2012Segmentation.py + :language: python + :start-after: """Read Dataset / get label""" + :end-before: """""" + +There are two label types in "VOC2012 Segmentation" dataset, which are ``semantic_mask`` and ``instance_mask``. We can +get the mask by ``Image.open()`` or get the mask url by ``get_url()``. +The information stored in :ref:`reference/label_format/SemanticMask:SemanticMask.all_attributes` is +attributes for every category in ``categories`` list of ``SEMANTIC_MASK`` of :ref:`catalog.json `. +The information stored in :ref:`reference/label_format/InstanceMask:InstanceMask.all_attributes` +is attributes for every instance. +See :ref:`reference/label_format/SemanticMask:SemanticMask` and :ref:`reference/label_format/InstanceMask:InstanceMask` label formats for more details. + +**************** + Delete Dataset +**************** + +.. literalinclude:: ../../../docs/code/VOC2012Segmentation.py + :language: python + :start-after: """Delete Dataset""" + :end-before: """""" diff --git a/docs/source/images/example-instancemask.png b/docs/source/images/example-instancemask.png new file mode 100644 index 000000000..5717c0a13 Binary files /dev/null and b/docs/source/images/example-instancemask.png differ diff --git a/docs/source/images/example-semanticmask.png b/docs/source/images/example-semanticmask.png new file mode 100644 index 000000000..e58c8c6fb Binary files /dev/null and b/docs/source/images/example-semanticmask.png differ diff --git a/docs/source/quick_start/examples.rst b/docs/source/quick_start/examples.rst index 59ed4e960..43d86df20 100644 --- a/docs/source/quick_start/examples.rst +++ b/docs/source/quick_start/examples.rst @@ -10,9 +10,9 @@ The following table lists a series of examples to help developers to use TensorB :align: center :widths: auto - ======================================================= ========================================================================== + ======================================================== ========================================================================= Examples Description - ======================================================= ========================================================================== + ======================================================== ========================================================================= :ref:`examples/DogsVsCats:Dogs vs Cats` | Topic: Dataset Management | Data Type: Image | Label Type: :ref:`reference/label_format/Classification:Classification` @@ -31,10 +31,14 @@ The following table lists a series of examples to help developers to use TensorB :ref:`examples/THCHS30:THCHS-30` | Topic: Dataset Management | Data Type: Audio | Label Type: :ref:`reference/label_format/Sentence:Sentence` + :ref:`examples/VOC2012Segmentation:VOC2012 Segmentation` | Topic: Dataset Management + | Data Type: Image + | Label Types: :ref:`reference/label_format/SemanticMask:SemanticMask`, + :ref:`reference/label_format/InstanceMask:InstanceMask` :ref:`examples/update_dataset:Update Dataset` | Topic: Update Dataset :ref:`examples/move_and_copy:Move And Copy` | Topic: Move And Copy :ref:`examples/merge_datasets:Merge Datasets` | Topic: Merge Datasets - ======================================================= ========================================================================== + ======================================================== ========================================================================= .. toctree:: :hidden: @@ -46,6 +50,7 @@ The following table lists a series of examples to help developers to use TensorB ../examples/NeolixOD ../examples/THCHS30 ../examples/Newsgroups20 + ../examples/VOC2012Segmentation ../examples/update_dataset ../examples/move_and_copy ../examples/merge_datasets