Metadata-Version: 2.2
Name: dash-picture-annotation
Version: 0.2.1
Summary: Dash porting version of the React project React Picture Annotation. Provide a simple annotation window for a single picture.
Author-email: Yuchen Jin <cainmagi@gmail.com>
Maintainer-email: Yuchen Jin <cainmagi@gmail.com>
License: MIT License
Project-URL: Homepage, https://github.com/cainmagi/dash-picture-annotation
Project-URL: Documentation, https://cainmagi.github.io/dash-picture-annotation/
Project-URL: Repository, https://github.com/cainmagi/dash-picture-annotation.git
Project-URL: Issues, https://github.com/cainmagi/dash-picture-annotation/issues
Project-URL: Changelog, https://github.com/cainmagi/dash-picture-annotation/blob/main/Changelog.md
Keywords: python,python3,python-library,dash,plotly-dash,python-dash,annotation,annotation-tool,image-annotation,labeling,image-labeling,object-detection,deep-learning,data-visualization
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Framework :: Dash
Classifier: Framework :: Flask
Classifier: Topic :: Database :: Front-Ends
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Image Processing
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: dash>=2.7.0
Requires-Dist: typing-extensions
Provides-Extra: dev
Requires-Dist: dash[dev]>=2.7.0; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: wheel; extra == "dev"
Requires-Dist: black; extra == "dev"
Provides-Extra: test
Requires-Dist: dash[dev,testing]>=2.7.0; extra == "test"
Requires-Dist: werkzeug; extra == "test"
Requires-Dist: pillow>=4; extra == "test"
Requires-Dist: numpy; extra == "test"
Requires-Dist: scikit-image>=0.16; extra == "test"
Requires-Dist: chromedriver-binary-auto; extra == "test"
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-base-url; extra == "test"
Requires-Dist: pytest-flask; extra == "test"
Requires-Dist: pytest-html; extra == "test"
Requires-Dist: pytest-metadata; extra == "test"
Requires-Dist: py; extra == "test"
Requires-Dist: pytest-selenium; extra == "test"
Requires-Dist: pytest-variables; extra == "test"
Requires-Dist: pytest-xdist; extra == "test"

# Dash Picture Annotation

<p><img alt="Banner" src="https://repository-images.githubusercontent.com/883421149/10c3593c-2d90-4eff-a3b5-761946985243"></p>

<p align="center">
  <a href="https://github.com/cainmagi/dash-picture-annotation/releases/latest"><img alt="GitHub release (latest SemVer)" src="https://img.shields.io/github/v/release/cainmagi/dash-picture-annotation?logo=github&sort=semver&style=flat-square"></a>
  <a href="https://github.com/cainmagi/dash-picture-annotation/releases"><img alt="GitHub all releases" src="https://img.shields.io/github/downloads/cainmagi/dash-picture-annotation/total?logo=github&style=flat-square"></a>
  <a href="https://github.com/cainmagi/dash-picture-annotation/blob/main/LICENSE"><img alt="GitHub" src="https://img.shields.io/github/license/cainmagi/dash-picture-annotation?style=flat-square&logo=opensourceinitiative&logoColor=white"></a>
  <a href="https://pypi.org/project/dash-picture-annotation"><img alt="PyPI - Downloads" src="https://img.shields.io/pypi/dm/dash-picture-annotation?style=flat-square&logo=pypi&logoColor=white&label=pypi"></a>
</p>
<p align="center">
  <a href="https://github.com/cainmagi/dash-picture-annotation/actions/workflows/python-package.yml"><img alt="GitHub Actions (Build)" src="https://img.shields.io/github/actions/workflow/status/cainmagi/dash-picture-annotation/python-package.yml?style=flat-square&logo=githubactions&logoColor=white&label=build"></a>
  <a href="https://github.com/cainmagi/dash-picture-annotation/actions/workflows/python-publish.yml"><img alt="GitHub Actions (Release)" src="https://img.shields.io/github/actions/workflow/status/cainmagi/dash-picture-annotation/python-publish.yml?style=flat-square&logo=githubactions&logoColor=white&label=release"></a>
</p>

Dash Picture Annotation is a Dash component library.

Dash porting version of the React project [React Picture Annotation :link:][git-react-picture-annotation]. Provide a simple annotation window for a single picture.

The following two figures compare the demos of the original React version and the ported Dash version. Since this project is just a dash component wrapper on the original React component, the performance is the same.

|   React Picture Annotation    |   Dash Picture Annotation   |
| :---------------------------: | :-------------------------: |
| ![demo-react][pic-demo-react] | ![demo-dash][pic-demo-dash] |

Compared to the original project, this project has the following special features that the original React project does not support:

1. Responsive sizing: The width of the annotator can be automatically adjusted according to the parent web element.
2. Different modes: When selecting an annotation, the modifier can be configured as an input box or a dropdown menu box.
3. Data sanitized: The data is simply sanitized. Even if a not standardized data is passed to the annotator, it still works.
4. Anti-mistakes: A threshold of the annotation size can be configured to prevent users create a tiny annotation item by mistake.
5. Disabled: A flag can be configured to make the annotator disabled.
6. Specified colors: A special color can be configured for an annotator with a specific comment. Different comments can have different colors.
7. Dynamic colors: Without specifying colors manually, a flag can enable the colors to be automatically calculated based on the hash code of the annotation comments.

Preview a quick video demo here:

https://github.com/user-attachments/assets/398fa4ff-4926-4594-a9c6-9bb92d170c63

## 1. Install

Intall the **latest released version** of this package by using the PyPI source:

``` sh
python -m pip install dash-picture-annotation
```

Or use the following commands to install **the developing version** from the GitHub Source when you have already installed [Git :hammer:][tool-git], [NodeJS :hammer:][tool-nodejs], and [Yarn :hammer:][tool-yarn]:

```bash
git clone https://github.com/cainmagi/dash-picture-annotation
cd dash-picture-annotation
python -m pip install -r requirements-dev.txt
yarn install
yarn build
python -m pip install .
```

## 2. Usage

The following signature shows the basic usage of this component.

``` python
import dash_picture_annotation as dpa

dpa.DashPictureAnnotation(
    id="annotator",
    style={"height": "80vh"},
    data=default_data,  # Can be `None`
    image="/assets/test_image.svg",  # Can be `None`
    options=None,
)
```

where the `data` is typed by `dpa.Annotations`. It should be formatted like this:

```json
{
  "timestamp": 0,
  "data": [
    {
      "id": "N5fewQ",
      "mark": {
        "x": -224.45, "y": 62.76, "width": 125.53, "height": 125.53, "type": "RECT"
      },
      "comment": "has-a-type"
    },
    {
      "id": "ibJMdK",
      "mark": {
        "x": -36.15, "y": 62.76, "width": 125.53, "height": 125.53, "type": "RECT"
      },
    },
    {
      "id": "...",
      "...": "...",
    }
  ]
}
```

A full demo for a minimal example can be found [here :link:][link-demo-minimal].

A full demo for an integrated application can be found [here :link:][link-demo-usage], where the basic usages are displayed.

## 3. Documentation

Check the documentation to find more details about the examples and APIs.

https://cainmagi.github.io/dash-picture-annotation/

## 4. Contributing

See [CONTRIBUTING.md :book:][link-contributing]

## 5. Changelog

See [Changelog.md :book:][link-changelog]

## 6. Acknowledgements

- [Kunduin/react-picture-annotation :link:][git-react-picture-annotation]: The original React component implementation of this project.

[git-react-picture-annotation]:https://github.com/Kunduin/react-picture-annotation

[tool-git]:https://git-scm.com/downloads
[tool-nodejs]:https://nodejs.org/en/download/package-manager
[tool-yarn]:https://yarnpkg.com/getting-started/install

[pic-demo-react]:https://raw.githubusercontent.com/cainmagi/dash-picture-annotation/main/display/demo-react.png
[pic-demo-dash]:https://raw.githubusercontent.com/cainmagi/dash-picture-annotation/main/display/demo-dash.png

[link-contributing]:https://github.com/cainmagi/dash-picture-annotation/blob/main/CONTRIBUTING.md
[link-changelog]:https://github.com/cainmagi/dash-picture-annotation/blob/main/Changelog.md

[link-demo-minimal]:https://github.com/cainmagi/dash-picture-annotation/blob/main/examples/minimal.py
[link-demo-usage]:https://github.com/cainmagi/dash-picture-annotation/blob/main/usage.py
