[](https://mybinder.org/v2/gh/gereleth/jupyter-bbox-widget/HEAD?filepath=examples%2Fintroduction.ipynb&urlpath=tree%2Fexamples%2Fintroduction.ipynb)
# jupyter\_bbox\_widget
A Jupyter widget for annotating images with bounding boxes. **See a [live demo on Binder](https://mybinder.org/v2/gh/gereleth/jupyter-bbox-widget/HEAD?filepath=examples%2Fintroduction.ipynb&urlpath=tree%2Fexamples%2Fintroduction.ipynb).**
```python
from jupyter_bbox_widget import BBoxWidget
widget = BBoxWidget(
image='fruit.jpg',
classes=['apple', 'orange', 'pear'],
)
widget
```
Create, edit, move, resize and delete bounding box annotations using the mouse.
Use `widget.bboxes` to get current annotations values:
```python
widget.bboxes
# [{'x': 377, 'y': 177, 'width': 181, 'height': 201, 'label': 'apple'},
# {'x': 219, 'y': 142, 'width': 169, 'height': 171, 'label': 'orange'},
# {'x': 43, 'y': 174, 'width': 234, 'height': 195, 'label': 'pear'}]
```
You can also assign to `widget.bboxes` to display any annotations. For example, use the output of an object detection model to do model-assisted labeling.
```python
widget.bboxes = [
{'x': 377, 'y': 177, 'width': 181, 'height': 201, 'label': 'apple'},
{'x': 219, 'y': 142, 'width': 169, 'height': 171, 'label': 'orange'},
{'x': 43, 'y': 174, 'width': 234, 'height': 195, 'label': 'pear'}
]
```
*Fruit photo by <a href="https://unsplash.com/@umanoide?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText">Umanoide</a> on <a href="https://unsplash.com/?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText">Unsplash</a>*
## Installation
You can install using `pip`:
```bash
pip install jupyter_bbox_widget
```
If you are using Jupyter Notebook 5.2 or earlier, you may also need to enable
the nbextension:
```bash
jupyter nbextension enable --py [--sys-prefix|--user|--system] jupyter_bbox_widget
```
## Usage
### Create and edit annotations with the mouse
- click and drag to create a bbox
- click and drag corners or edges to resize a bbox
- click and drag inside a bbox to move it
- in order to change a label select a new label below the image and click on label text
### Keyboard shortcuts
When you click inside the widget area it will gain focus and start receiving keyboard events. An outline usually indicates that the element is focused. Normal Jupyter keyboard shortcuts won't work in this state. To unfocus the widget area click outside it or press `Esc`.
Some shortcuts act on the selected bbox. New bboxes are selected automatically when created. You can also select a bbox by clicking on it. Selected bbox is displayed on top of others and with a thicker border.
- Digit keys 1-9 and 0 select a class label.
- `Esc` unfocuses the widget
- `Enter` is the same as pressing Submit button
- `Space` is the same as pressing Skip button
- `Tab` / `Shift-Tab` select next/previous bbox.
- Keys acting on the selected bbox (assuming a QWERTY keyboard, other layouts should use any keys in the same locations):
- `W` move up
- `A` move left
- `S` move down
- `D` move right
- `Q` shrink width
- `E` grow width
- `R` grow height
- `F` shrink height
- `C` assign selected class label
- Holding `Shift` while pressing movement keys will increase step size
### Skip and Submit events
You can define functions that will be called automatically when you press Skip or Submit buttons. This is useful for creating a workflow for annotating multiple images.
```python
@widget.on_skip
def skip():
# move on to the next image
@widget.on_submit
def save():
# do stuff to save current annotations and move on
```
There is an example of a simple annotation workflow in [`examples/introduction.ipynb`](https://github.com/gereleth/jupyter-bbox-widget/blob/main/examples/introduction.ipynb) notebook.
### View only mode
You can disable editing of annotations by setting `widget.view_only = True`. This is useful for viewing annotation outputs without accidentally changing them.
### Recording additional data
Sometimes you need to record more info about an object than just a location and a class label. For example, you might want to specify whether the object is in focus or blurred, record its size or other properties.
Let's say we want to apply a rating on a scale from 1 to 5 to every object in the image. We create a slider widget to edit the rating values:
```python
w_rating = widgets.IntSlider(value=3, min=1, max=5, description='Rating')
```
And we attach it to the bbox widget.
```python
widget.attach(w_rating, name='rating')
```
As a result all bboxes created afterwards will have a `rating` property and the `w_rating` widget can be used to display and manipulate the rating of the currently selected bbox.
Any number and any kind of `ipywidgets` widgets may be used in this way for creating richer annotations - number inputs, text inputs, checkboxes and so on (see [widget list](https://ipywidgets.readthedocs.io/en/stable/examples/Widget%20List.html)).
The notebook in [`examples/introduction.ipynb`](https://github.com/gereleth/jupyter-bbox-widget/blob/main/examples/introduction.ipynb) has an example and a more detailed explanation of this feature.
## Changelog
- v0.5.0
- enabled use of `widget.on_skip` and `widget.on_submit` methods as decorators
- v0.4.0
- exposed selected class label to the python side as `widget.label`
- v0.3.4
- set max-width: 100% on image so that it respects layout
- v0.3.3
- fixed bboxes not updating after class change by keyboard shortcut
- v0.3.2
- added `hide_buttons` option
- fixed bbox delete icon not displayed properly
- v0.3.1
- unselect a bbox on click outside in view only mode
- fixed a bug with overwriting attached properties on unselect
- v0.3.0
- added `view_only` mode
- v0.2.0
- added Skip and Submit buttons
- added attach widget functionality for recording extra properties
- multiple fixes and improvements
- v0.1.0
- initial release
## Development Installation
This project was inspired by a blogpost [Creating Reactive Jupyter Widgets With Svelte](https://cabreraalex.medium.com/creating-reactive-jupyter-widgets-with-svelte-ef2fb580c05) and was created based on [widget-svelte-cookiecutter](https://github.com/cabreraalex/widget-svelte-cookiecutter) template.
```bash
# First install the python package. This will also build the JS packages.
pip install -e .
```
When developing your extensions, you need to manually enable your extensions with the
notebook / lab frontend. For lab, this is done by the command:
```
jupyter labextension install @jupyter-widgets/jupyterlab-manager --no-build
jupyter labextension install .
```
For classic notebook, you can run:
```
jupyter nbextension install --sys-prefix --symlink --overwrite --py jupyter_bbox_widget
jupyter nbextension enable --sys-prefix --py jupyter_bbox_widget
```
Note that the `--symlink` flag doesn't work on Windows, so you will here have to run
the `install` command every time that you rebuild your extension. For certain installations
you might also need another flag instead of `--sys-prefix`, but we won't cover the meaning
of those flags here.
### How to see your changes
#### Typescript:
To continuously monitor the project for changes and automatically trigger a rebuild, start Jupyter in watch mode:
```bash
jupyter lab --watch
```
And in a separate session, begin watching the source directory for changes:
```bash
npm run watch
```
After a change wait for the build to finish and then refresh your browser and the changes should take effect.
#### Python:
If you make a change to the python code then you will need to restart the notebook kernel to have it take effect.
Raw data
{
"_id": null,
"home_page": "https://github.com/gereleth/jupyter-bbox-widget",
"name": "jupyter-bbox-widget",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "Jupyter,Widgets,IPython",
"author": "gereleth",
"author_email": "daria.voznyak@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/ca/3c/e370d7277f77855cb0655c57d8e4b8ad32449c82c9c41f191280062d23a8/jupyter_bbox_widget-0.5.0.tar.gz",
"platform": "Linux",
"description": "[](https://mybinder.org/v2/gh/gereleth/jupyter-bbox-widget/HEAD?filepath=examples%2Fintroduction.ipynb&urlpath=tree%2Fexamples%2Fintroduction.ipynb)\n\n# jupyter\\_bbox\\_widget\n\nA Jupyter widget for annotating images with bounding boxes. **See a [live demo on Binder](https://mybinder.org/v2/gh/gereleth/jupyter-bbox-widget/HEAD?filepath=examples%2Fintroduction.ipynb&urlpath=tree%2Fexamples%2Fintroduction.ipynb).**\n\n```python\nfrom jupyter_bbox_widget import BBoxWidget\nwidget = BBoxWidget(\n image='fruit.jpg',\n classes=['apple', 'orange', 'pear'],\n)\nwidget\n```\n\n\n\nCreate, edit, move, resize and delete bounding box annotations using the mouse.\n\nUse `widget.bboxes` to get current annotations values:\n\n```python\nwidget.bboxes\n# [{'x': 377, 'y': 177, 'width': 181, 'height': 201, 'label': 'apple'},\n# {'x': 219, 'y': 142, 'width': 169, 'height': 171, 'label': 'orange'},\n# {'x': 43, 'y': 174, 'width': 234, 'height': 195, 'label': 'pear'}]\n```\n\nYou can also assign to `widget.bboxes` to display any annotations. For example, use the output of an object detection model to do model-assisted labeling.\n\n```python\nwidget.bboxes = [\n {'x': 377, 'y': 177, 'width': 181, 'height': 201, 'label': 'apple'},\n {'x': 219, 'y': 142, 'width': 169, 'height': 171, 'label': 'orange'},\n {'x': 43, 'y': 174, 'width': 234, 'height': 195, 'label': 'pear'}\n]\n```\n\n*Fruit photo by <a href=\"https://unsplash.com/@umanoide?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText\">Umanoide</a> on <a href=\"https://unsplash.com/?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText\">Unsplash</a>*\n\n## Installation\n\nYou can install using `pip`:\n\n```bash\npip install jupyter_bbox_widget\n```\n\nIf you are using Jupyter Notebook 5.2 or earlier, you may also need to enable\nthe nbextension:\n\n```bash\njupyter nbextension enable --py [--sys-prefix|--user|--system] jupyter_bbox_widget\n```\n\n## Usage\n\n### Create and edit annotations with the mouse\n\n- click and drag to create a bbox\n- click and drag corners or edges to resize a bbox\n- click and drag inside a bbox to move it\n- in order to change a label select a new label below the image and click on label text\n\n### Keyboard shortcuts\n\nWhen you click inside the widget area it will gain focus and start receiving keyboard events. An outline usually indicates that the element is focused. Normal Jupyter keyboard shortcuts won't work in this state. To unfocus the widget area click outside it or press `Esc`.\n\nSome shortcuts act on the selected bbox. New bboxes are selected automatically when created. You can also select a bbox by clicking on it. Selected bbox is displayed on top of others and with a thicker border.\n\n- Digit keys 1-9 and 0 select a class label.\n- `Esc` unfocuses the widget\n- `Enter` is the same as pressing Submit button\n- `Space` is the same as pressing Skip button\n- `Tab` / `Shift-Tab` select next/previous bbox.\n- Keys acting on the selected bbox (assuming a QWERTY keyboard, other layouts should use any keys in the same locations):\n - `W` move up\n - `A` move left\n - `S` move down\n - `D` move right\n - `Q` shrink width\n - `E` grow width\n - `R` grow height\n - `F` shrink height\n - `C` assign selected class label\n - Holding `Shift` while pressing movement keys will increase step size\n\n### Skip and Submit events\n\nYou can define functions that will be called automatically when you press Skip or Submit buttons. This is useful for creating a workflow for annotating multiple images. \n\n```python\n@widget.on_skip\ndef skip():\n # move on to the next image\n\n@widget.on_submit\ndef save():\n # do stuff to save current annotations and move on\n```\n\nThere is an example of a simple annotation workflow in [`examples/introduction.ipynb`](https://github.com/gereleth/jupyter-bbox-widget/blob/main/examples/introduction.ipynb) notebook.\n\n### View only mode\n\nYou can disable editing of annotations by setting `widget.view_only = True`. This is useful for viewing annotation outputs without accidentally changing them.\n\n### Recording additional data\n\nSometimes you need to record more info about an object than just a location and a class label. For example, you might want to specify whether the object is in focus or blurred, record its size or other properties.\n\nLet's say we want to apply a rating on a scale from 1 to 5 to every object in the image. We create a slider widget to edit the rating values:\n\n```python\nw_rating = widgets.IntSlider(value=3, min=1, max=5, description='Rating')\n```\n\nAnd we attach it to the bbox widget.\n\n```python\nwidget.attach(w_rating, name='rating')\n```\n\nAs a result all bboxes created afterwards will have a `rating` property and the `w_rating` widget can be used to display and manipulate the rating of the currently selected bbox.\n\nAny number and any kind of `ipywidgets` widgets may be used in this way for creating richer annotations - number inputs, text inputs, checkboxes and so on (see [widget list](https://ipywidgets.readthedocs.io/en/stable/examples/Widget%20List.html)). \n\nThe notebook in [`examples/introduction.ipynb`](https://github.com/gereleth/jupyter-bbox-widget/blob/main/examples/introduction.ipynb) has an example and a more detailed explanation of this feature.\n\n## Changelog\n\n- v0.5.0 \n - enabled use of `widget.on_skip` and `widget.on_submit` methods as decorators\n- v0.4.0\n - exposed selected class label to the python side as `widget.label`\n- v0.3.4\n - set max-width: 100% on image so that it respects layout\n- v0.3.3\n - fixed bboxes not updating after class change by keyboard shortcut\n- v0.3.2\n - added `hide_buttons` option\n - fixed bbox delete icon not displayed properly\n- v0.3.1\n - unselect a bbox on click outside in view only mode\n - fixed a bug with overwriting attached properties on unselect\n- v0.3.0\n - added `view_only` mode\n- v0.2.0\n - added Skip and Submit buttons\n - added attach widget functionality for recording extra properties\n - multiple fixes and improvements\n- v0.1.0\n - initial release\n\n\n## Development Installation\n\nThis project was inspired by a blogpost [Creating Reactive Jupyter Widgets With Svelte](https://cabreraalex.medium.com/creating-reactive-jupyter-widgets-with-svelte-ef2fb580c05) and was created based on [widget-svelte-cookiecutter](https://github.com/cabreraalex/widget-svelte-cookiecutter) template.\n\n```bash\n# First install the python package. This will also build the JS packages.\npip install -e .\n```\n\nWhen developing your extensions, you need to manually enable your extensions with the\nnotebook / lab frontend. For lab, this is done by the command:\n\n```\njupyter labextension install @jupyter-widgets/jupyterlab-manager --no-build\njupyter labextension install .\n```\n\nFor classic notebook, you can run:\n\n```\njupyter nbextension install --sys-prefix --symlink --overwrite --py jupyter_bbox_widget\njupyter nbextension enable --sys-prefix --py jupyter_bbox_widget\n```\n\nNote that the `--symlink` flag doesn't work on Windows, so you will here have to run\nthe `install` command every time that you rebuild your extension. For certain installations\nyou might also need another flag instead of `--sys-prefix`, but we won't cover the meaning\nof those flags here.\n\n### How to see your changes\n\n#### Typescript:\n\nTo continuously monitor the project for changes and automatically trigger a rebuild, start Jupyter in watch mode:\n\n```bash\njupyter lab --watch\n```\n\nAnd in a separate session, begin watching the source directory for changes:\n\n```bash\nnpm run watch\n```\n\nAfter a change wait for the build to finish and then refresh your browser and the changes should take effect.\n\n#### Python:\n\nIf you make a change to the python code then you will need to restart the notebook kernel to have it take effect.\n\n\n",
"bugtrack_url": null,
"license": "BSD",
"summary": "A Jupyter widget for annotating images with bounding boxes",
"version": "0.5.0",
"project_urls": {
"Homepage": "https://github.com/gereleth/jupyter-bbox-widget"
},
"split_keywords": [
"jupyter",
"widgets",
"ipython"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "960f9e1f50a37d0776dede4d260584369bf5e1f956670a796e50c9b565f32de7",
"md5": "95ca86cf466c7301a473529ca86b274c",
"sha256": "37277c8b4dc79170d2fca64243dcea7c019830ab2d9f096e30e7e88ba7c58d40"
},
"downloads": -1,
"filename": "jupyter_bbox_widget-0.5.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "95ca86cf466c7301a473529ca86b274c",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 367800,
"upload_time": "2022-07-23T12:46:18",
"upload_time_iso_8601": "2022-07-23T12:46:18.685293Z",
"url": "https://files.pythonhosted.org/packages/96/0f/9e1f50a37d0776dede4d260584369bf5e1f956670a796e50c9b565f32de7/jupyter_bbox_widget-0.5.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ca3ce370d7277f77855cb0655c57d8e4b8ad32449c82c9c41f191280062d23a8",
"md5": "9c21041543fd708518ec611f8b4391be",
"sha256": "24b6599757420da2894d86486e76f9953ec628e13177730a73fa39bea8545543"
},
"downloads": -1,
"filename": "jupyter_bbox_widget-0.5.0.tar.gz",
"has_sig": false,
"md5_digest": "9c21041543fd708518ec611f8b4391be",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 562843,
"upload_time": "2022-07-23T12:55:47",
"upload_time_iso_8601": "2022-07-23T12:55:47.048437Z",
"url": "https://files.pythonhosted.org/packages/ca/3c/e370d7277f77855cb0655c57d8e4b8ad32449c82c9c41f191280062d23a8/jupyter_bbox_widget-0.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-07-23 12:55:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "gereleth",
"github_project": "jupyter-bbox-widget",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "jupyter-bbox-widget"
}
JSON
