https://github.com/twsl/pytorchcocotools
Unofficial APIs for the MS-COCO dataset using PyTorch
https://github.com/twsl/pytorchcocotools
coco coco-dataset lightning pycocotools pytorch pytorch-lightning
Last synced: 3 months ago
JSON representation
Unofficial APIs for the MS-COCO dataset using PyTorch
- Host: GitHub
- URL: https://github.com/twsl/pytorchcocotools
- Owner: twsl
- License: mit
- Created: 2023-07-03T21:31:03.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2025-02-09T17:08:29.000Z (3 months ago)
- Last Synced: 2025-02-09T17:15:19.577Z (3 months ago)
- Topics: coco, coco-dataset, lightning, pycocotools, pytorch, pytorch-lightning
- Language: Python
- Homepage: https://twsl.github.io/pytorchcocotools/
- Size: 2.17 MB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
Awesome Lists containing this project
README
# 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).
> [!WARNING]
> This is work in progress, feel free to contribute!
## 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)