Coco to Custom Vision (in Azure)

A simple utility to upload a COCO dataset format to custom vision and vice versa. This can be used to backup your custom vision object detection projects into a storage account and restore it later or use AzureML to create a more custom CV model.

Currently the scripts work with Object Detection but can be easily updated to work with Classification.

Installation

Install from pip:

pip install coco2customvision

Usage

To export a custom vision project to an Azure storage account use the following:

coco2customvision export -sk "<storage_account_key>" -sn <storage_account_name> -sc <storage_account_container_name> -cvk <custom_vision_key> -cve <custom_vision_endpoint> -cvp <custom_vision_project_name> coco_dataset_filename.json

To import a coco dataset that is located in an Azure storage account container into a custom vision project (the project may not exist yet):

coco2customvision import -sk "<storage_account_key>" -sn <storage_account_name> -sc <storage_account_container_name> -cvk <custom_vision_key> -cve <custom_vision_endpoint> -cvp <custom_vision_project_name> coco_dataset_filename.json

You can get the parameters from:

Custom vision: custom_vision_key, custom_vision_endpoint, custom_vision_project_name
Azure portal: storage_account_key, storage_account_name, storage_account_container_name

Code development

If you want to contribute to this code base, clone the repo and follow these instructions.

Development installation

Install module in editable/develop mode (-e) and include the development dependencies (the [dev] argument you see) using the following:

pip install -e .[dev]

For tests to complete, you need to configure some secrets. These secrets are retrieved from environment variables. To avoid adding these environment variables in your system, you need to create a pytest.ini file based on the pytest.ini.template template and fill in all needed values. Use the following links to retrieve the corresponding settings:

The pytest.ini file is in .gitignore to avoid pushing credentials accidentally.

To run all tests:

python -m pytest . -c pytest.ini

or use the VSCode Test Explorer to even debug your code.

[Optional] Invoking the dev code from command line

If you installed the module in develop mode you can use it directly as seen in the instructions above. You can also use the module reference, as seen bellow.

To export a custom vision project to an Azure storage account use the following:

python -m src.coco2customvision export -sk "<storage_account_key>" -sn <storage_account_name> -sc <storage_account_container_name> -cvk <custom_vision_key> -cve <custom_vision_endpoint> -cvp <custom_vision_project_name> coco_dataset_filename.json

To import a coco dataset that is located in an Azure storage account container into a custom vision project (the project may not exist yet):

python -m src.coco2customvision import -sk "<storage_account_key>" -sn <storage_account_name> -sc <storage_account_container_name> -cvk <custom_vision_key> -cve <custom_vision_endpoint> -cvp <custom_vision_project_name> coco_dataset_filename.json

Code quality practices

Before making any commit you can invoke the pre-commit.bat file which does the following:

Format the code using black:
```
python -m black . 
```
Ensure that there is no flake8 error:
```
python -m flake8 .
```
Ensure all test pass:
```
python -m pytest . -c pytest.ini
```
Ensure setup.cfg file is consistently formatted:
```
setup-cfg-fmt setup.cfg
```

Publishing to pypi

To create a release you need to create an annotated tag:

git tag -a v0.1.0 -m "First version of the tool"

You can view existing tags and their comments (-n) using:

git tag -n

Run a build to create the corresponding version artifacts under the dist folder:

python -m build

Then push them to testpypi to verify:

pip install --upgrade twine
twine upload --repository testpypi dist/*

Verify results in the test Pypi instance. You can try installing in a new python environment using:

pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple coco2customvision

If you decide to make some more changes, you can delete a tag using the following:

git tag -d v0.1.0

Note: You will not be able to push the same version to the test Pypi instance. As a work around you can increase the prerelease 4th digit e.g. 0.1.0.1.

When you are ready push changes to remote and let github actions publish the package to the production Pypi. Just push the tag to GitHub and the CD action will create the release:

git push origin --tags

Note that currently the CD process is kicked when you push the tag and it doesn't do the CI part. So make sure your code is passing the CI part before tagging and pushing the tag to GitHub.

References

Here is a list of related projects and references to this effort:

Custom vision blob connector python tool to upload images to custom vision from blob storage.
CustomVision.COCO C# tool to train models using a COCO definition file.
VoTT2COCO converts VoTT json files to COCO format.
Azure cognitive services python SDK
Custom vision SDK
Description of the COCO format
Coco2Yolo
Unofficial tool to download a CVS project in COCO format: https://github.com/shonohs/cvsutils, https://github.com/shonohs/simpledataset
```
cvs_download_project <project_id> downloaded/
dataset_convert_to downloaded/images.txt coco coco_output/
```
Custom Vision Autotrainer: Found it after this project was completed. Haven't played with it.

List of Python related references:

Writing python in VSCode
Fixtures in pytest
Click arguments parser
Packaging projects
Dependency management
Docs authoring pack, highly recommended collection of VSCode plugins.

rndazurescript / Coco2CustomVision