# pytorchcocotools
[](https://github.com/twsl/pytorchcocotools/actions/workflows/build.yaml)
[](https://github.com/twsl/pytorchcocotools/actions/workflows/docs.yaml)
[](https://pypi.org/project/pytorchcocotools/)
[](https://pypi.org/project/pytorchcocotools/)
[](https://squidfunk.github.io/mkdocs-material/)
[](https://python-poetry.org/)
[](https://github.com/astral-sh/ruff)
[](.pre-commit-config.yaml)
[](https://microsoft.github.io/pyright/)
[](https://github.com/PyCQA/bandit)
[](https://github.com/twsl/pytorchcocotools/releases)
[](https://github.com/copier-org/copier)
[](LICENSE)
Unofficial APIs for the MS-COCO dataset using PyTorch.
Uses the official [repository](https://github.com/ppwwyyxx/cocoapi) of the `pycocotools` packages as reference.
The file format is explained in the [official documentation](https://cocodataset.org/#format-data) and nicely summarized [here](https://www.youtube.com/watch?v=h6s61a_pqfM).
## Features
- Strongly typed COCO data format [represetation](./src/pytorchcocotools/internal/structure/)
- Drop-in compatible `COCO` and `COCOeval` classes
- (Almost) drop-in compatible `mask` methods
- Pure `torch` implementation
- `torchvision` data set using the latest transformation API
- fully unit tested and documented
## Installation
With `pip`:
```bash
python -m pip install pytorchcocotools
```
With [`poetry`](https://python-poetry.org/):
```bash
poetry add pytorchcocotools
```
## How to use it
Pretty much all you need to do is to change the import statement from `pycocotools` to `pytorchcocotools`:
```diff
-import pycocotools
+import pytorchcocotools
```
So all imports look like this:
```python
from pytorchcocotools.coco import COCO
from pytorchcocotools.cocoeval import COCOeval
...
```
## API
> [!WARNING]
> While the API is mostly compatible with the original `pycocotools` package, there are some differences.
> For some methods you need to adapt the handling of the return type. See the examples below.
> [!NOTE]
> All methods are documented with detailed type hints.
### `mask`
All methods now have a optional `device` and `requires_grad` parameters that allows to specify the device on which the masks should be created and whether gradients are required. This is useful for acceleration.
> [!IMPORTANT]
> `decode`, `encode`, `toBbox` and `frPyObjects` now always return the batch/channel dimension implementation as opposed to a single return element if only a single element was passed.
> This was done to make the API more consistent by providing single, defined return types, but is open for further discussion.
### `COCO`
One major difference is that the `COCO` class now uses a strongly typed data structure to represent the COCO data format. This makes it easier to work with the data and to understand the structure of the data, but also might cause problems with data sources that do not strictly follow the data format.
### `COCOeval`
Strongly typed as well. Includes also minor fixes, e.g. the `__str__` now also returns the `stats`.
### Other additions
- `pytorchcocotools.utils.coco.download.CocoDownloader`: While `gsutils rsync` is the officially recommended way to download the data, this allows you to trigger the download from Python.
- The `logger` property in both all classes from the `logging` module replaces the `print` command, so you can fully customize it.
- `pytorchcocotools.torch.dataset.CocoDetection`: A drop-in replacement for the dataset from `torchvision`, now strongly typed using the new `transforms.v2` api.
## Docs
```bash
poetry run mkdocs build -f ./docs/mkdocs.yml -d ./_build/
```
## Update template
```bash
copier update --trust -A --vcs-ref=HEAD
```
## Credits
This project was generated with [](https://github.com/twsl/python-project-template)
Raw data
{
"_id": null,
"home_page": "https://twsl.github.io/pytorchcocotools/",
"name": "pytorchcocotools",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "pytorchcocotools, pytorch, pycocotools, pytorch-lightning, lightning, coco",
"author": "twsl",
"author_email": "45483159+twsl@users.noreply.github.com",
"download_url": "https://files.pythonhosted.org/packages/27/90/b9687cfd2cd9755de06c1ab1b80cd406f5d46c97a4e8272424a8a6efacb3/pytorchcocotools-0.1.1.tar.gz",
"platform": null,
"description": "# pytorchcocotools\n\n[](https://github.com/twsl/pytorchcocotools/actions/workflows/build.yaml)\n[](https://github.com/twsl/pytorchcocotools/actions/workflows/docs.yaml)\n\n[](https://pypi.org/project/pytorchcocotools/)\n[](https://pypi.org/project/pytorchcocotools/)\n[](https://squidfunk.github.io/mkdocs-material/)\n[](https://python-poetry.org/)\n[](https://github.com/astral-sh/ruff)\n[](.pre-commit-config.yaml)\n[](https://microsoft.github.io/pyright/)\n[](https://github.com/PyCQA/bandit)\n[](https://github.com/twsl/pytorchcocotools/releases)\n[](https://github.com/copier-org/copier)\n[](LICENSE)\n\nUnofficial APIs for the MS-COCO dataset using PyTorch.\nUses the official [repository](https://github.com/ppwwyyxx/cocoapi) of the `pycocotools` packages as reference.\n\nThe file format is explained in the [official documentation](https://cocodataset.org/#format-data) and nicely summarized [here](https://www.youtube.com/watch?v=h6s61a_pqfM).\n\n## Features\n\n- Strongly typed COCO data format [represetation](./src/pytorchcocotools/internal/structure/)\n- Drop-in compatible `COCO` and `COCOeval` classes\n- (Almost) drop-in compatible `mask` methods\n- Pure `torch` implementation\n- `torchvision` data set using the latest transformation API\n- fully unit tested and documented\n\n## Installation\n\nWith `pip`:\n\n```bash\npython -m pip install pytorchcocotools\n```\n\nWith [`poetry`](https://python-poetry.org/):\n\n```bash\npoetry add pytorchcocotools\n```\n\n## How to use it\n\nPretty much all you need to do is to change the import statement from `pycocotools` to `pytorchcocotools`:\n\n```diff\n-import pycocotools\n+import pytorchcocotools\n```\n\nSo all imports look like this:\n\n```python\nfrom pytorchcocotools.coco import COCO\nfrom pytorchcocotools.cocoeval import COCOeval\n\n...\n```\n\n## API\n\n> [!WARNING]\n> While the API is mostly compatible with the original `pycocotools` package, there are some differences.\n> For some methods you need to adapt the handling of the return type. See the examples below.\n\n> [!NOTE]\n> All methods are documented with detailed type hints.\n\n### `mask`\n\nAll methods now have a optional `device` and `requires_grad` parameters that allows to specify the device on which the masks should be created and whether gradients are required. This is useful for acceleration.\n\n> [!IMPORTANT]\n> `decode`, `encode`, `toBbox` and `frPyObjects` now always return the batch/channel dimension implementation as opposed to a single return element if only a single element was passed.\n> This was done to make the API more consistent by providing single, defined return types, but is open for further discussion.\n\n### `COCO`\n\nOne major difference is that the `COCO` class now uses a strongly typed data structure to represent the COCO data format. This makes it easier to work with the data and to understand the structure of the data, but also might cause problems with data sources that do not strictly follow the data format.\n\n### `COCOeval`\n\nStrongly typed as well. Includes also minor fixes, e.g. the `__str__` now also returns the `stats`.\n\n### Other additions\n\n- `pytorchcocotools.utils.coco.download.CocoDownloader`: While `gsutils rsync` is the officially recommended way to download the data, this allows you to trigger the download from Python.\n- The `logger` property in both all classes from the `logging` module replaces the `print` command, so you can fully customize it.\n- `pytorchcocotools.torch.dataset.CocoDetection`: A drop-in replacement for the dataset from `torchvision`, now strongly typed using the new `transforms.v2` api.\n\n## Docs\n\n```bash\npoetry run mkdocs build -f ./docs/mkdocs.yml -d ./_build/\n```\n\n## Update template\n\n```bash\ncopier update --trust -A --vcs-ref=HEAD\n```\n\n## Credits\n\nThis project was generated with [](https://github.com/twsl/python-project-template)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Unofficial APIs for the MS-COCO dataset using PyTorch",
"version": "0.1.1",
"project_urls": {
"Documentation": "https://twsl.github.io/pytorchcocotools/",
"Homepage": "https://twsl.github.io/pytorchcocotools/",
"Repository": "https://github.com/twsl/pytorchcocotools"
},
"split_keywords": [
"pytorchcocotools",
" pytorch",
" pycocotools",
" pytorch-lightning",
" lightning",
" coco"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c55c8cacc4416de1d13253b3f4370efff6692fdfb5c8d96cb273677f63bf2c3c",
"md5": "b5df30c8aa51dc2ce35dcaf0d1bad23e",
"sha256": "a13b61517642d1a4aac69e575658356a81b6f99e8099b9cd901e579e5100fdad"
},
"downloads": -1,
"filename": "pytorchcocotools-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b5df30c8aa51dc2ce35dcaf0d1bad23e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 66654,
"upload_time": "2025-02-09T16:46:46",
"upload_time_iso_8601": "2025-02-09T16:46:46.741651Z",
"url": "https://files.pythonhosted.org/packages/c5/5c/8cacc4416de1d13253b3f4370efff6692fdfb5c8d96cb273677f63bf2c3c/pytorchcocotools-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2790b9687cfd2cd9755de06c1ab1b80cd406f5d46c97a4e8272424a8a6efacb3",
"md5": "b84bd1a86be9ed5186f7ea0dba603672",
"sha256": "7be700b5e052fe77febebb843fa77253a8804560eef522a84f2bb95c46723ad1"
},
"downloads": -1,
"filename": "pytorchcocotools-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "b84bd1a86be9ed5186f7ea0dba603672",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 51158,
"upload_time": "2025-02-09T16:46:47",
"upload_time_iso_8601": "2025-02-09T16:46:47.806192Z",
"url": "https://files.pythonhosted.org/packages/27/90/b9687cfd2cd9755de06c1ab1b80cd406f5d46c97a4e8272424a8a6efacb3/pytorchcocotools-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-09 16:46:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "twsl",
"github_project": "pytorchcocotools",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pytorchcocotools"
}
JSON
