Skip to main content

Yet another data labeling tool

Project description

QSL: Quick and Simple Labeler

QSL Screenshot

QSL is a simple, open-source image labeling tool. It supports:

  • Bounding box and polygon labeling.
  • Configurable keyboard shortcuts for labels.
  • Loading images stored locally, on the web, or in cloud storage (currently only AWS S3).
  • Pre-loading images in a queue to speed up labeling.
  • Deployment as shared service with support for OAuth (currently only GitHub and Google)

Please note that that QSL is still under development and there are likely to be major bugs, breaking changes, etc. Bug reports and contributions are welcome!

Getting Started

Install qsl using pip install qsl. You cannot install qsl directly from the GitHub repository because the frontend assets must be built manually.

You can start a simple project labeling files from your machine using a command like the following.

qsl simple-label path/to/files/*.jpg my-qsl-project.json

Note that if my-qsl-project.json already exists and has files in it, these files will be added (the old files will still be in the project). If it does not exist, an empty project file will be created.

You can navigate to the the QSL labeling interface in a browser at http://localhost:5000 (use the --host and --port flags to modify this). From the interface, click the link to Configure project to set which labels you want to apply to images. Labels can be applied at the image or box level. There are three kinds of labels you can use:

  • Single: You select 0 or 1 entry from a list of options.
  • Multiple: You select 0 or more entries from a list of options.
  • Text: A free-form text field.

After configuring the project, you can immediately start labeling single images from the main project page. When you're done (or just want to pause) hit Ctrl+C at the prompt where you started QSL. The labels will be available in my-qsl-project.json. You can parse this yourself pretty easily, but you can also save yourself the trouble by using the data structures within QSL. For example, the following will load the image- and box-level labels for a project into a pandas dataframe.

import pandas as pd
import qsl.types.web as qtw

with open("my-qsl-project.json", "r") as f:
    project = qtw.Project.parse_raw(f.read())

image_level_labels = pd.DataFrame(project.image_level_labels())
box_level_labels = pd.DataFrame(project.box_level_labels())

Labeling Remotely Hosted Files

Note that QSL also supports labeling files hosted remotely in cloud storage (only AWS S3 is supported right now) or at a public URL. So, for example, if you want to label some files in an S3 bucket and on a web site, you can use the following command:

qsl simple-label 's3://my-bucket/images/*.jpg' 's3://my-bucket/other/*.jpg' 'http://my-site/image.jpg' my-qsl-project.json

Please note that paths like this must meet some criteria.

  • On most platforms / shells, you must use quotes (as shown in the example).
  • Your AWS credentials must be available in a form compatible with the default boto3 credential-finding methods and those credentials must be permitted to use the ListBucket and GetObject actions.

Advanced Use Cases

Documentation for the more advanced use cases is not yet available though they are implemented in the package. Advanced use cases include things like:

  • Hosting a central QSL server with multiple users and projects
  • Authentication with Google or GitHub OAuth providers
  • Batched labeling for images with shared default labels

In short, you can launch a full-blown QSL deployment simply by doing the following.

  1. Set the following environment variables to configure the application.
    • DB_CONNECTION_STRING: A database connection string, used to host the application data. If not provided, a SQLite database will be used in the current working directory called qsl-labeling.db.
    • OAUTH_INITIAL_USER: The initial user that will be an administrator for the QSL instance.
    • OAUTH_PROVIDER: The OAuth provider to use (currently github and google are supported)
    • OAUTH_CLIENT_SECRET: The OAuth client secret.
    • OAUTH_CLIENT_ID: The OAuth client ID.
  2. Execute qsl label (instead of qsl simple-label) to launch the application (use --host and --port to modify how the application listens for connections).

Development

  1. Install Poetry.
  2. Clone this repository.
  3. Initialize your development environment using make init
  4. Launch a live reloading version of the frontend and backend using make develop.

Project details


Release history Release notifications | RSS feed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

qsl-0.0.18.tar.gz (1.8 MB view details)

Uploaded Source

Built Distribution

qsl-0.0.18-py3-none-any.whl (1.8 MB view details)

Uploaded Python 3

File details

Details for the file qsl-0.0.18.tar.gz.

File metadata

  • Download URL: qsl-0.0.18.tar.gz
  • Upload date:
  • Size: 1.8 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.4.1 importlib_metadata/4.0.1 pkginfo/1.7.0 requests/2.25.1 requests-toolbelt/0.9.1 tqdm/4.60.0 CPython/3.8.8

File hashes

Hashes for qsl-0.0.18.tar.gz
Algorithm Hash digest
SHA256 de5e735c7e35b9e51e911b0e6809be78e908df9826f73408093f1495c2fdc749
MD5 fe33b9ade9a7b995ee4cedfec295884b
BLAKE2b-256 38b94bcb156b7d0c92b55ee9e0fbba014a1e1a50b2ffef94964143c289e6f5d6

See more details on using hashes here.

Provenance

File details

Details for the file qsl-0.0.18-py3-none-any.whl.

File metadata

  • Download URL: qsl-0.0.18-py3-none-any.whl
  • Upload date:
  • Size: 1.8 MB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.4.1 importlib_metadata/4.0.1 pkginfo/1.7.0 requests/2.25.1 requests-toolbelt/0.9.1 tqdm/4.60.0 CPython/3.8.8

File hashes

Hashes for qsl-0.0.18-py3-none-any.whl
Algorithm Hash digest
SHA256 8af9563001af7dc8d02aa75cbc82bd51e05ede60db9a285cc8f55725ff5a95d1
MD5 faf5e94c171fbe7c9005f88ca0116e37
BLAKE2b-256 45f15d1a8b1c153829f1f3c38dec383c5a8fb89999b63195d3ec7d45bee73e61

See more details on using hashes here.

Provenance

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page