# Labeller
Quickly set up an image labelling web application for the tagging of images by humans for supervised machine learning tasks.
## Introduction
*Labeller* allows you to quickly set up an image tagging web application for labelling of images.
### Usage
1. Install _Labeller_ using `pip install labeller` from the command line
2. Navigate to the directory where you wish to create your web application. This directory should contain a subdirectory named `static/images` that contains the images you wish to label
3. Run `python -m labeller class_1 class_2 ... class_n` where `class_1 class_2 ... class_n` is a list of your class names separated by spaces
4. Run `python -m flask run` to start the web application
Example:
```bash
$ python -m labeller car tree bike house
$ python -m flask run
```
See the Options section below for configuration options.
Run `python -m labeller -h` for quick help.
### How Labeller Works
When you create a new labelling application, _Labeller_ will generate a web application based on the number of classes you have defined during initialisation. Images stored in `static/images` will be displayed randomly to the user, and they can be labelled with one of the classes provided during the app initialisation.
The built application will have the following structure:
```
project_folder
├── app.py
├── db
│ └── labels.db
├── static
│ ├── favicon.ico
│ ├── images
│ │ ├── im_1.jpg
│ │ ├── im_2.jpg
│ │ ├── ...
│ │ └── im_n.jpg
│ └── styles
│ └── dashboard.css
└── templates
├── about.html
├── footer.html
├── index.html
├── labels.html
└── navbar.html
```
The `labels.db` file is an SQLite database containing the labels for the images that have been labelled so far. To export them to CSV format, run the following:
```
$ sqlite3 -header -csv labels.db "select * from labels;" > labels.csv
```
## FAQ
- I want to clear the database and start labelling again
- Delete the sqlite database in the `db` directory. The app will regenerate a new, empty database when run if no database exists.
- How can I export the data from the database as a CSV file?
- Try something like: `sqlite3 -header -csv labels.db "select * from labels;" > labels.csv`
Ensure you place your images in a the directory path `static/images`, so that a path to an image would be `./static/images/im_1.png` for example. In other words your directory structure should look as follows before you build your application:
```
project_folder
└── static
└── images
├── im_1.jpg
├── im_2.jpg
├── im_3.jpg
├── ...
└── im_n.jpg
```
## Options
Currently, the only user definable parameters is the list of class names. This will change as the application develops.
### Flask Options
_Labeller_ uses Flask as its web development framework. You can pass arguments to Flask as normal when invoking `python -m flask run`, or through environment variables. For example development mode can be enabled by setting an environment variable, e.g: `export FLASK_ENV=development` in Linux (in Windows use `set FLASK_ENV=development` or `$env:FLASK_ENV = "development"` in Powershell).
Some common options that can be passed with `python -m flask run` are:
- To serve the application over the network pass `--host=0.0.0.0`, so `python -m flask run --host=0.0.0.0`
- To use a different port other than the default of 5000, e.g. port 5001, pass `--port 5001`, so `python -m flask run --port 5001`
## Requirements
- Python >=3.5
The following Python packages are required, and will be downloaded automatically by `pip` during installation:
- `flask`
- `flask-bootstrap`
as well and their requirements.
## Known Issues
- HTML formatting of generated output needs work
- Images that are particularly large may have issues rendering and this will be fixed in the next update
## Future Work
- Text snippet labelling
- Consensus labelling (combining labelling efforts across users)
- Multi class labelling (labelling an image with more than one label)
- Free-text tagging/labelling
- Allow an option to resize all images in the `images` directory to a certain size when creating the web app
- API access for running instances to get image tags
- Provide option to not use CDNs for JQuery and Bootstrap
- Docker image?
Raw data
{
"_id": null,
"home_page": "https://github.com/mdbloice/Labeller",
"name": "labeller",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Marcus D. Bloice",
"author_email": "marcus.bloice@medunigraz.at",
"download_url": "https://files.pythonhosted.org/packages/06/50/8d6132cdf947f881d3a0ccb11f970ff881a6ffa1b2e0f44330595056d70d/labeller-0.2.0.tar.gz",
"platform": null,
"description": "# Labeller\n\nQuickly set up an image labelling web application for the tagging of images by humans for supervised machine learning tasks.\n\n## Introduction\n\n*Labeller* allows you to quickly set up an image tagging web application for labelling of images.\n\n### Usage\n\n1. Install _Labeller_ using `pip install labeller` from the command line\n2. Navigate to the directory where you wish to create your web application. This directory should contain a subdirectory named `static/images` that contains the images you wish to label\n3. Run `python -m labeller class_1 class_2 ... class_n` where `class_1 class_2 ... class_n` is a list of your class names separated by spaces\n4. Run `python -m flask run` to start the web application\n\nExample:\n\n```bash\n$ python -m labeller car tree bike house\n$ python -m flask run\n```\nSee the Options section below for configuration options.\n\nRun `python -m labeller -h` for quick help.\n\n### How Labeller Works\nWhen you create a new labelling application, _Labeller_ will generate a web application based on the number of classes you have defined during initialisation. Images stored in `static/images` will be displayed randomly to the user, and they can be labelled with one of the classes provided during the app initialisation.\n\nThe built application will have the following structure:\n\n```\nproject_folder\n\u251c\u2500\u2500 app.py\n\u251c\u2500\u2500 db\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 labels.db\n\u251c\u2500\u2500 static\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 favicon.ico\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 images\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 im_1.jpg\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 im_2.jpg\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 ...\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 im_n.jpg\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 styles\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 dashboard.css\n\u2514\u2500\u2500 templates\n \u251c\u2500\u2500 about.html\n \u251c\u2500\u2500 footer.html\n \u251c\u2500\u2500 index.html\n \u251c\u2500\u2500 labels.html\n \u2514\u2500\u2500 navbar.html\n```\n\nThe `labels.db` file is an SQLite database containing the labels for the images that have been labelled so far. To export them to CSV format, run the following:\n\n```\n$ sqlite3 -header -csv labels.db \"select * from labels;\" > labels.csv\n```\n\n## FAQ\n\n- I want to clear the database and start labelling again\n - Delete the sqlite database in the `db` directory. The app will regenerate a new, empty database when run if no database exists.\n- How can I export the data from the database as a CSV file?\n - Try something like: `sqlite3 -header -csv labels.db \"select * from labels;\" > labels.csv`\n\nEnsure you place your images in a the directory path `static/images`, so that a path to an image would be `./static/images/im_1.png` for example. In other words your directory structure should look as follows before you build your application:\n\n```\nproject_folder\n\u2514\u2500\u2500 static\n \u2514\u2500\u2500 images\n \u251c\u2500\u2500 im_1.jpg\n \u251c\u2500\u2500 im_2.jpg\n \u251c\u2500\u2500 im_3.jpg\n \u251c\u2500\u2500 ...\n \u2514\u2500\u2500 im_n.jpg\n```\n\n## Options\n\nCurrently, the only user definable parameters is the list of class names. This will change as the application develops.\n\n### Flask Options\n_Labeller_ uses Flask as its web development framework. You can pass arguments to Flask as normal when invoking `python -m flask run`, or through environment variables. For example development mode can be enabled by setting an environment variable, e.g: `export FLASK_ENV=development` in Linux (in Windows use `set FLASK_ENV=development` or `$env:FLASK_ENV = \"development\"` in Powershell).\n\nSome common options that can be passed with `python -m flask run` are:\n\n- To serve the application over the network pass `--host=0.0.0.0`, so `python -m flask run --host=0.0.0.0`\n- To use a different port other than the default of 5000, e.g. port 5001, pass `--port 5001`, so `python -m flask run --port 5001`\n\n## Requirements\n\n- Python >=3.5\n\nThe following Python packages are required, and will be downloaded automatically by `pip` during installation:\n\n- `flask`\n- `flask-bootstrap`\n\nas well and their requirements.\n\n## Known Issues\n\n- HTML formatting of generated output needs work\n- Images that are particularly large may have issues rendering and this will be fixed in the next update\n\n## Future Work\n\n- Text snippet labelling\n- Consensus labelling (combining labelling efforts across users)\n- Multi class labelling (labelling an image with more than one label)\n- Free-text tagging/labelling\n- Allow an option to resize all images in the `images` directory to a certain size when creating the web app\n- API access for running instances to get image tags\n- Provide option to not use CDNs for JQuery and Bootstrap\n- Docker image?\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Create image labelling software for machine learning applications.",
"version": "0.2.0",
"project_urls": {
"Homepage": "https://github.com/mdbloice/Labeller"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1aea753fcda8e2d7120d4c3fc2f9f73689b5c6251b4ad92e46b1abdabfb53a3e",
"md5": "68d96ab4486374f00e19b13bddad9217",
"sha256": "bec9fbaae3bfa3a6f5503931c9d758d3cbc277f1df5eb511802378717d45d222"
},
"downloads": -1,
"filename": "labeller-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "68d96ab4486374f00e19b13bddad9217",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 16851,
"upload_time": "2023-10-05T10:54:15",
"upload_time_iso_8601": "2023-10-05T10:54:15.511497Z",
"url": "https://files.pythonhosted.org/packages/1a/ea/753fcda8e2d7120d4c3fc2f9f73689b5c6251b4ad92e46b1abdabfb53a3e/labeller-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "06508d6132cdf947f881d3a0ccb11f970ff881a6ffa1b2e0f44330595056d70d",
"md5": "62cd46db92dc177d733b61fd354aa14a",
"sha256": "5c5c36761cc5eaadae947cfb98703411a696bde38bac59d796a993c789ff5910"
},
"downloads": -1,
"filename": "labeller-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "62cd46db92dc177d733b61fd354aa14a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 17338,
"upload_time": "2023-10-05T10:54:17",
"upload_time_iso_8601": "2023-10-05T10:54:17.343390Z",
"url": "https://files.pythonhosted.org/packages/06/50/8d6132cdf947f881d3a0ccb11f970ff881a6ffa1b2e0f44330595056d70d/labeller-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-05 10:54:17",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mdbloice",
"github_project": "Labeller",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "flask",
"specs": []
},
{
"name": "flask-bootstrap",
"specs": []
}
],
"lcname": "labeller"
}
JSON
